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第 一 部 分 Spring framework 概述 


Spring framework 是 一 个 轻 量 级 的 解决 方案 ， 在 构建 一 站 式 企业 级 应 用 程序 上 有 很 
大 的 RAE o Spring 是 模块 化 的 ， 允 许 你 使 用 仅 需 要 的 部 分 ， 而 不 需要 引入 其 余部 
分 。 你 可 以 使 用 loC 容器 ， 和 Struts 一 起 使 用 ， 而 且 你 也 可 以 仅仅 使 用 Hibernate 
整合 代码 或 者 是 JDBC 抽象 层 。Spring framework 支持 声明 式 的 事务 管理 ， 通 过 
RMI 或 Web Service 远程 访问 业务 逻辑 代码 ， 并 且 提 供 多 种 持久 化 数据 的 选择 。 
它 提 供 馈 了 一 个 全 功能 的 MVC 框架 ， 允 许 你 显 式 地 整合 AOP 到 软件 中 。 


Spring 被 设计 成 非 侵入 式 的 ， 也 就 是 说 你 的 业务 逻辑 代码 通常 是 不 会 对 Spring 框 
RAG 产生 依赖 的 。 在 你 的 整合 层面 (比如 数据 访问 层 ) ， 一 些 依赖 于 数据 访问 技 
术 和 Spring 的 类 库 是 会 存在 的 。 但 是 ， 也 很 容易 将 这 些 依赖 从 你 剩余 的 代码 中 分 


本 文档 是 Spring 框架 特性 的 参考 指南 。 如 果 你 有 任何 想法 ， 建 议 或 是 对 本 文档 的 
疑问 ， 请 发 送 到 用 户 邮件 列表 中 或 者 是 在 线 论 坛 中 ， 论 坛 地 址 是 http://forum.spri 
ngsource.org ° 


大 大 


第 1 Spring Framework 介绍 


Spring Framework 是 一 个 Java 平台 ， 它 提供 了 对 用 Java 语言 开发 应 用 程序 的 一 
种 广泛 的 基础 支持 。Spring 本 身 来 控制 这 个 基础 ， 那 么 你 就 可 以 集中 精力 于 应 用 
程序 的 开发 了 。 

Spring 允许 你 从 “普通 Java 对 象 (POJO) "来 构建 应 用 程序 ， 并 且 将 非 侵入 地 企业 
BM 务 应 用 于 POJO 中 。 这 种 能 力 不 仅 适用 于 Java SE 编程 模型 ， 也 适用 于 全 部 
或 部 分 的 Java EE ° 

作为 应 用 程序 的 开发 人 员 ， 下 面 就 是 可 以 使 用 Spring 平台 所 含 优点 的 例子 : 

编写 Java 方法 来 执行 数据 库 事务 而 不 需要 处 理 相 关 的 事务 API 。 

编写 本 地 的 Java 方法 来 访问 远程 程序 而 不 需要 处 理 远程 访问 API 。 

编写 本 地 的 Java 方法 来 执行 管理 操作 而 不 需要 处 理 JMX 的 API 。 

编写 本 地 的 Java 方法 来 处 理 消息 操作 而 不 需要 处 理 JMS 的 API 。 


1.1 依赖 注入 和 控制 反 转 
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“问题 是 ，[ 它 们 ] 反 向 控制 哪 一 方面 ?”，2004 4 > Martin Fowler 在 他 个 人 站 点 提出 
了 这 个 关于 控制 反 转 (loC) 的 问题 。Fowler 建议 重 命名 这 个 原则 ， 使 得 它 更 好 地 
自我 解释 ， 同 时 提出 了 依赖 注入 。 


要 深入 了 解 loC 和 DI， 可 以 参 者 Fowler 的 文章 ， 地 址 是 : 
http://mart inf owler.com/artic les/injection.html 


Java 应 用 程序 -- 一 个 宽松 的 术语 ， 尝 括 了 从 被 限制 的 applet 到 n 层 服务 器 端的 企 
LA 应 用 程序 的 全 部 - 典型 的 应 用 是 ， 包 含 了 组 成 独特 应 用 程序 的 合作 对 象 。 那 么 
在 应 用 程序 中 的 这 些 对 象 就 会 有 相互 依赖 关系 。 


尽管 Java 平台 提供 了 丰富 的 应 用 程序 开发 功能 ， 但 是 它 也 缺乏 组 织 基 本 模块 到 整 
体 的 方式 ， 而 是 把 这 个 任务 留 给 了 系统 架构 师 和 开发 人 员 去 解决 。 也 就 是 说 ， 你 可 
以 设计 如 工厂 ， 抽 象 工厂 ， 构 建 者 ， 装 饰 者 和 服务 定位 器 等 设计 模式 来 组 合 各 个 
类 ， 以 及 构成 该 应 用 程序 的 对 象 的 实例 。 然 而 ， 这 些 模式 都 是 最 简单 的 : 最 佳 的 做 
法 是 给 定 一 个 名 称 ， 并 且 描 述 这 个 模 式 做 了 些 什么 ， 在 哪里 可 以 应 用 它 ， 它 所 强调 
的 问题 是 什么 等 等 。 模 式 可 以 使 得 你 必须 自己 实现 的 最 佳 实践 形式 化 。 


Spring Framework 的 控制 反 转 (Inversion of Control > loC) 组 件 提供 了 组 合 不 同 
的 组 件 到 完整 可 用 的 应 用 程序 的 形式 化 方法 。Spring Framework 编写 了 形式 化 的 
设计 模式 作为 顶级 对 象 ， 你 可 以 用 来 整合 到 你 自己 的 应 用 程序 中 。 很 多 组 织 和 研究 
机 构 使 用 Spring Framework 的 这 个 方式 来 设计 健壮 的 ， 可 维护 的 应 用 程序 。 


1.2 模块 


1.2 模块 


Spring Framework 包含 了 很 多 特性 ， 并 且 组 织 成 20 个 模块 。 这 些 模块 分 为 核心 容 
器 ， 数 据 访 问 /整合 ， ,Web， AOP (Aspect Oriented Programming > i 9 +7 i 4 
42) ， 基 础 组 件 和 测 试 ， 在 下 图 中 来 展示 这 些 模 块 。 





Spring 框架 概要 


1.2.1 核心 容器 


核心 容器 (4.1 节 ) 包含 了 核心 (Core) ，Bean 组 件 (Beans) ， 上 下 文 
(Context) 和 表 达 式 语言 (Expression a. 模块 。 


核心 和 Bean (4. 节 ) 模块 提供 了 框架 部 分 的 基础 ， Ay loC 和 依赖 注入 特性 。 


BeanFactory 是 工厂 模式 的 精密 实现 。 它 去 掉 了 编程 实现 单 例 的 需要 ， 并 允许 你 解 
除 配置 信息 ， 以 及 实际 程序 逻辑 的 特定 依赖 之 间 的 耦合 。 

上 下 文 (4.14 节 ) 模块 构建 了 由 核心 和 Bean (4.1 节 ) 模块 提供 的 坚实 基础 : 它 

可 以 让 你 以 框架 中 的 风格 来 访问 对 象 ， 这 和 INDI 的 注册 是 相似 的 。 上 下 文 模块 集 
成 了 来 自 Bean 模块 的 特性 ， 并 且 加 入 了 对 国际 化 (比如 使 用 资源 束 ) 的 支持 ， 事 
件 传播 ， 资 源 加 载 和 Servlet 容 器 显 式 创建 上 下 文 。 上 下 文 模块 也 支持 Java EE 特 
性 ， 比 如 EJB > JMX 和 基本 的 远程 调用 。 


ApplicationContext 接口 是 上 下 文 模块 的 焦点 。 
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表达 式 语言 (第 7 章 ) 模块 提供 了 强大 的 表达 式 语言 ， 在 运行 时 查询 和 操作 对 象 
图 。 这 是 JSP 2.1 规范 中 的 统一 表达 式 语言 (Unified EL) 的 一 个 扩展 。 该 表达 式 
语言 支持 设置 和 获取 属性 值 ， 属 性 定义 ， 方 法 调用 ， 访 问 数组 ， 集 合 以 及 索引 的 上 
下 文 。 支 持 逻 辑 和 数字 运算 ， 命 名 变量 。 还 支持 从 Spring 的 loc 容器 中 以 名 称 来 
获取 对 象 。 它 也 支持 list 的 投影 和 选择 操作 ， 还 有 普通 的 list RH © 


1.2.2 数据 访问 /整合 


数据 访问 /整合 层 由 JDBC，ORM，OXM ，JMS 和 事务 模块 组 成 。 


JDBC (13.1 节 ) 模块 提供 了 JDBC WRA’ CHIRT REKKI JDBC 编码 ， 但 解析 
了 数据 库 提供 商定 义 的 特定 错误 代码 。 


ORM (14.1 节 ) 模块 提供 了 对 流行 的 对 象 -实体 映射 API 的 整合 层 ， 包 含 

JPA (14.5 节 ) > JDO (14.4 节 ) > Hibernate (14.3 节 ) 和 iBatis (14.6 7) ° 
使 用 ORM 包 你 就 可 以 使 用 全 部 的 O/R- 映 射 框架 并 联合 其 它 Spring 提供 的 特性 ， 
比如 之 前 所 提 到 的 简单 声明 式 的 事务 管理 特性 。 


OXM (第 15 章 ) 模块 提供 了 支持 JAXB ° Castor > XMLBeans ° JiBX ， 以 及 
Xstream 对 对 象 /XML 映射 实现 的 抽象 层 。 


Java 消息 服务 (JMS， 第 22 章 ) 模块 包含 生成 和 处 理 消息 的 特性 。 
事务 (第 11 章 ) 模块 支持 对 实现 特定 接口 的 类 和 所 有 POJO (普通 Java 对 象 ) 的 
编程 式 和 声明 式 的 事务 管理 。 


1.2.3 Web 


Web 层 由 Web，Web-Servlet，Web-Struts 和 Web-Portlet 模块 组 成 。 


Spring 的 Web 模块 提供 了 基本 的 面向 Web 整合 的 特性 ， 比 如 文件 上 传 功能 ，loC 
容器 的 初始 化 使 用 了 Servlet 的 监听 器 和 变形 的 Web 应 用 上 下 文 。 它 还 包含 了 和 
Web 相关 的 Spring 远程 调用 支持 的 部 分 。 


Web-Servlet 模块 包含 了 Spring 对 Web 应 用 的 模型 -视图 -控制 器 (MVC > 16.1 
节 ) 模式 的 实现 。Spring 的 MVC 框架 提供 了 一 个 在 领域 模型 代码 和 Web 表单 之 
间 的 整洁 分 离 ， 并 且 整合 了 其 它 所 有 Spring 框架 的 特性 。 


Web-Struts 模块 包含 了 使 用 Spring 应 用 程序 整合 经 典 的 Strtus Web 层 的 支持 类 。 
要 注意 这 个 支持 从 Spring 3.0 开始 就 废弃 了 。 那 么 可 以 考虑 迁移 应 用 程序 到 Struts 
2.0 和 Spring 的 整 合 或 者 是 单纯 的 Spring MVC 方案 。 


Web-Portlet 模块 提供 用 于 portlet 环境 和 Web-Servlet 模块 功能 镜像 的 MVC 实 
现 。 


1.2.4 AOP 和 基础 组 件 


Spring 的 AOP (8.1 节 ) 模块 提供 了 AOP 联盟 -允许 的 的 面向 切面 的 编程 实现 ， 允 
许 你 定 义 如 方法 -拦截 器 和 横 切 点 来 整洁 地 解 耦 应 该 被 分 离 的 功能 实现 代码 。 使 用 
源 代码 级 的 元 数 据 功 能 ， 也 可 以 混合 行为 信息 到 代码 中 ， 这 个 方式 和 .NET 的 属性 
很 相似 。 

分 离 的 Aspects 模块 提供 对 AspectJ 的 整合 。 


础 组 件 模块 提供 了 对 类 的 基础 支持 ， 还 有 类 加 载 器 的 实现 来 用 于 特定 的 应 用 服务 


vad 


AS 


H 
W 


1.2.5 测试 


测试 模块 支持 Spring 224+ > Junit 或 Test NG 的 测试 。 它 提供 了 Spring 应 用 上 下 
文 的 一 致 加载 并 缓存 这 些 上 下 文 内 容 。 它 也 提供 mock 对 象 ， 你 可 以 用 来 孤立 地 测 
试 代码 。 


1.3 使 用 方案 


1.3 使 用 方案 


前 面 描述 的 模块 使 得 Spring 可 以 在 很 多 方案 中 作为 业务 逻辑 实现 的 选择 ， 从 
applet 到 使 用 了 Spring 的 事务 管理 功能 和 Web 框架 整合 ， 功 能 完善 的 企业 级 应 用 


程序 。 
Spring Framework Funtime 
| Web Serviet 


Core Container 








Expression 
Language 


Core | Context | | 




















典型 地 功能 完善 的 Spring Web 应 用 


Spring 的 声明 式 事务 管理 特性 (11.5 节 ) 使 得 Web 应 用 程序 可 以 全 部 事务 化 ， 就 
好 像 


使 用 了 EJB 容器 管理 的 事务 。 全 部 的 自 定义 业务 逻辑 可 以 使 用 简单 的 POJO RE 
现 并 且 被 Spring 的 loC 容器 来 管理 。 其 它 的 服务 包含 对 发 送 邮 件 的 支持 ， 验 证 对 
Web 层 独 立 ， 这 可 以 让 你 选择 在 哪里 执行 验证 规则 。Spring 的 ORM 支持 对 
JPA，Hibernate,JDO 和 iBatis 进行 了 整合 ; 比如 ， 当 使 用 Hibernate 时 ， 你 可 以 
继续 使 用 已 有 的 映射 文件 和 标准 的 Hibernate 的 SessionFactory 配置 。 表 单 控制 
器 LE 地 整合 了 Web 层 和 领 域 模 型 ， 也 去 除了 ActionForm 或 其 它 为 领域 模 
型 转换 HTTP 参数 的 类 的 需要 。 
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1.3 使 用 方案 











Core Container 


Beans | Core | | Context | Expression 


Language 








Instrumentation 








Transactions 








使 用 了 第 三 方 Web 框架 的 Spring PAA 有 时 ， 开 发 和 运行 环境 并 不 允许 你 完全 转 
换 到 一 个 不 同 的 框架 中 。Spring Framework 不 强制 你 使 用 其 中 的 部 分 ; 它 并 不 是 

一 个 所 有 或 没有 的 方案 。 已 有 使 用 了 WebWork > Struts > Tapestry 或 其 它 UI 框架 
构建 的 前 端 应 用 程序 也 可 以 使 用 基于 Spring 的 中 Ra RTE ， 这 就 了 许 你 
去 使 用 Spring 的 事务 特性 。 你 仅仅 需要 做 的 是 给 业务 逻辑 装 
ApplicationContext， 对 整合 的 Web 层 使 用 WebApplicationContext 。 
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1.3 使 用 方案 








Core Container 





f ) ) ( it i 
Beans | Core | Context Expression 
| | | | Language } 


is 





远程 调用 使 用 方案 


当 你 需要 通过 Web Service 访问 已 有 的 代码 时 ， 你 可 以 使 用 Spring 的 Hessian- > 
Burlap-，Rmi- 或 JaxPpcProxyFactory 类 。 对 已 有 的 应 用 程序 开启 远程 访问 并 不 
难 。 








Expression 
Language 








Application Server (e.g. WebSphere, WebLogic, JBoss) 


EJB- 包装 已 有 的 POJO 

Spring Framework 也 提供 了 对 企业 级 Java Bean (EJB， 译 者 注 ) 的 访问 和 抽象 层 
(第 21 章 ) ， 这 就 可 以 重用 已 有 的 POJO， 可 以 扩展 、 和 包装 它们 到 无 状态 会 话 

bean， 不 安全 的 Web 应 用 程序 可 能 也 需要 声明 式 安全 。 


28 


1.3.1 依赖 管理 和 命名 规约 


依赖 管理 和 依赖 注入 是 不 同 的 概念 。 要 在 应 用 程序 中 添加 Spring 的 优雅 特性 (上 比 
如 依赖 注入 ) ， 你 需要 放置 所 需 的 类 库 〈jar 文件 ) ， 并 且 添 加 到 运行 时 环境 的 类 
路 径 中 ， 通 常 在 编译 时 也 是 需要 这 些 类 库 文件 的 。 这 些 依赖 不 是 注入 的 虚拟 组 件 ， 
而 是 文件 系统 (通常 来 说 是 这 样 ) 上 的 物理 资源 。 依 赖 管理 的 过 程 包括 定位 资源 ， 
存储 它们 ， 并 将 它们 添加 到 类 路 径 中 。 依 赖 可 以 是 直接 的 (比如 应 用 程序 在 运行 时 
需要 Spring) ， 或 者 是 间接 的 (比如 应 用 程 序 需要 的 commons-dbcp 组 件 还 依赖 
于 commons-pool 组 件 ) 。 间 接 的 依赖 也 被 认为 是 “过 度 的 "， 而 且 那 些 依赖 本 身 就 
难以 识别 和 管理 。 


如 果 你 决定 使 用 Spring， 那 么 你 需要 获得 Spring 的 jar 包 ， 其 中 要 包括 你 所 需要 使 
用 的 Spring 的 模块 。 为 了 使 用 的 便捷 ，Spring 被 打包 成 各 个 模块 的 集合 ， 尽 可 能 
地 分 离 其 中 的 相 互 依 赖 ， 那 么 如 果 你 不 想 编写 Web 应 用 程序 ， 就 不 需要 添加 
spring-web 模块 的 jar 包 。 要 参考 Spring 模块 的 库 ， 本 指南 使 用 了 一 个 可 
以 速记 的 命名 规约 ，spring- 或 者 spring-.jar ， 这 里 的 “* ”代表 了 各 模块 的 
短 名 称 〈( 比 如 ，spring-core ，spring-webmvc，spring-jms 等 ) ° EIRE jar 
文件 命名 或 许 就 是 这 种 形式 的 (参考 下 面 的 示例 ) ， 但 也 有 可 能 不 是 这 种 情况 ， 通 
常 它 的 文件 名 中 还 包含 一 个 版 本 号 (比如 ， spring-core-3.0.0.RELEASE.jar) ° 


通常 ，Spring 在 四 个 不 同 的 地 方 发 布 组 件 : 


e 在 社区 下 载 点 http://www.springsource.org/dow nloads/comm unity。 在 这 儿 你 
可 以 找到 所 有 的 Spring jar 包 ， 它 们 被 压缩 到 一 个 zip 文件 中 ， 可 以 自由 下 
载 。 这 里 jar 包 的 命名 从 3.0 版 本 开始 ， 都 以 org.springframework.*-.jar 格式 
进行 。 


Maven 的 中 央 库 ， 也 是 Maven 默认 检索 的 资源 库 ， 它 并 不 会 检索 特殊 的 配置 
来 使 用 。 很 多 Spring 所 依赖 的 常用 类 库 也 可 以 从 Maven 的 中 央 库 中 获得 ， 同 
时 Spring 社区 的 绝 大 多 数 用 户 都 使 用 Maven 作为 依赖 管理 工具 ， 这 对 于 他 们 
来 说 是 很 方便 的 。 这 里 的 jar 包 的 命名 规则 是 spring-*-.jar 格式 的 ， 并 且 
Maven 里 的 groupld 是 org.springframework -° 


企业 级 资源 库 (Enterprise Bundle Repository > EBR) ， 这 是 由 SpringSource 
组 织 运营 的 ， 同 时 也 提供 了 和 Spring 整合 的 所 有 类 库 。 对 于 所 有 Spring 的 
jar 包 及 其 依赖 ， 这 里 也 有 Maven 和 Ivy 的 资源 库 ， 同 时 这 里 还 有 很 多 开发 人 
员 在 使 用 Spring 编写 应 用 程序 时 能 用 到 的 其 它 大 量 常用 类 库 。 而 且 ， 发 布 的 
版 本 ， 里 程 碑 版 本 和 开发 版 本 也 都 部 署 在 这 里 。 这 里 jar 文 件 的 命名 规则 
和 从 社区 下 载 的 (org,springframework,*-<version>,jar ) 一 致 ， 
并 且 所 依赖 的 外 部 类 库 (不 是 来 自 SpringSource 的 ) 也 是 使 用 的 这 种 “长 命 
un 式 ， 并 以 com.springsource 作为 前 级 。 可 以 参考 FAQ 部 分 获取 更 多 信 


。 在 Amazon S3 为 开发 和 里 程 碑 版 本 发 布 (最 终 发 布 的 版 本 这 里 也 会 有 ) 而 设 
置 的 公共 Maven 资源 库 。Jar 文件 的 名 称 和 Maven 中 央 库 是 一 样 的 ， 那 么 这 
里 是 获取 Spring 开发 版 本 的 地 方 ， 其 它 的 类 库 是 部 署 于 Maven P REA o Ap 
么 ， 首 先 你 要 决定 的 事情 是 如 何 管理 这 些 依赖 : 很 多 人 使 用 自动 化 的 系统 ， 比 
如 Maven 和 Ivy， 但 是 你 也 可 以 手动 下 载 所 有 的 jar 文件 。 当 使 用 Maven 或 
Ivy 获取 Spring 时 ， 之 后 你 就 需要 决定 从 哪里 来 获取 它们 。 通 常 来 说 ， 如 果 你 
关注 OSGI 的 话 ， 那 么 就 使 用 EBR， 因 为 它 对 所 有 的 Spring 依赖 兼容 


OSGi， 比 如 Hibernate 和 Freemarker。 如 果 对 OSGi 不 感 兴 趣 ， 那 么 使 用 哪 
个 下 载 都 是 可 以 的 ， 但 是 他 们 也 各 有 利 藉 。 通 常 来 讲 ， 为 你 的 项 目 选择 一 个 或 
者 备用 的 一 个 ; 但 是 请 不 要 混用 。 因 为 相对 于 Maven 中 央 库 而 言 ，EBR 组 件 
非常 需要 一 个 不 同 的 命名 规则 ， 那 么 这 就 特别 重要 了 。 


表 1.1 Maven 中 央 库 和 SpringSource EBR 资源 库 的 比较 


特性 
OSGi 的 兼容 
组 件数 量 
一 致 的 命名 规 
约 


命名 规约 : 
Groupld 


命名 规约 : 
Artifactld 


命名 规约 : 
Version 


发 布 


质量 保证 


主机 


搜索 工具 


和 
SpringSource 
工具 整合 


Maven 中 央 库 
不 明确 


成 千 上 万 ; 所 有 种 


没有 


相 弄 。 新 组 件 通常 
使 用 域名 ， 比 如 
org.slf4j ° 4 21+ 
通常 仅仅 使 用 组 件 
名 ， 比 如 log4j。 


相 异 。 通 常 是 项 目 
或 模块 名 ， 使 用 连 
FRE AA? 比如 
spring-core ， 


log4j ° 


相 异 。 很 多 新 的 组 
件 使 用 m.m.m 或 
m.m.m.X (m 是 
数字 ，X EL 

本 ) 。 老 的 使 用 
m.m。 有 一 些 也 不 
是 。 顺序 是 确定 的 
但 通常 并 不 可 靠 ， 
所 以 不 是 严格 的 可 
# 0 
通常 是 自动 通过 
rsync 或 源码 控制 
更 新 。 项 目 作 者 可 
以 上 传 独立 的 jar 
文件 到 JIRA ° 


根据 政策 。 精 确 度 
是 作者 的 责任 。 


Contegix 提供 。 由 
Sonatype 和 一 些 
镜像 构成 。 


很 多 
通过 和 Maven 依 
赖 管理 的 STS 来 
整合 


EBR 
是 


几 百 个 ; 是 Spring 整合 中 会 用 到 的 


有 


始 的 域名 或 主 包 的 根 路 径 ， 
org.springframework 


捆绑 符号 名 称 ， 从 主 包 的 路 径 分 离 ， 比 
如 org.springframework.beans。 如 果 
jar 需要 修补 以 保证 兼容 OSGi’ BAR 
附加 com.springsource ， 比 如 
com.springsource.org.apache.log4j 


OSGi 版 本 数字 m.m.m.X ， 比 如 
3.0.0.RC3。 文本 标识 符 使 用 相同 的 数 
字 值 规定 版 本 的 字母 顺序 。 


手动 (由 SpringSource 控制 的 JIRA) 


宽泛 的 OSGi 清单 ，Maven POM 和 Ivy 
元 数据 。QA 由 Spring 团队 执行 。 

由 SpringSource 的 S3 构成 
http://www.springsource.com/repository 


通过 1 ，Roo ，CloudFoundry 的 
STS 进行 宽泛 整合 


1.3.1.1 Spring 依赖 和 基于 Spring 


尽管 Spring 提供 对 整合 的 支持 ， 以 及 对 大 量 企业 级 应 用 及 其 外 部 工具 的 支持 ， 那 
么 它 也 有 心 保 持 它 的 强制 依赖 在 一 个 绝对 小 的 数目 上 : 你 不 需要 为 了 简单 的 使 用 去 
定位 并 下 载 


(甚至 是 自动 地 ) 大 量 的 jar 来 使 用 Spring。 对 于 基本 的 依赖 注入 那 只 需要 一 个 必 
须 的 外 部 依赖 ， 就 是 日 志 (可 以 参考 下 面 关 于 日 志 的 深入 介绍 ) 。 


下 面 ， 我 们 来 概述 一 下 配置 一 个 基于 Spring 的 应 用 程序 所 需 的 基本 配置 ， 首 先 使 
用 


Maven 和 lvy。 在 所 有 的 示例 中 ， 如 果 有 哪 一 点 不 清楚 ， 可 以 参考 你 所 使 用 的 依赖 
管理 系统 的 相关 文档 ， 或 者 参考 一 些 示例 代码 ~ Spring 本 身 在 构建 时 使 用 了 Ivy 来 
管理 依赖 ， 而 我 们 


大 多 数 的 示例 却 使 用 Maven。 


1.3.1.2 Maven 依赖 管理 


如 果 你 正 使 用 Maven 来 进行 依赖 管理 ， 那么 你 就 不 需要 明确 地 提供 日 志 依 赖 。 上 比 
如 ， 要 为 应 用 程序 配置 创建 应 用 上 下 文 并 使 用 依赖 注入 特性 ， 那 么 ， 你 的 Maven 
依赖 配置 文件 可 以 是 这 样 的 : 


<dependencies> 
<dependency> 
<grouplId>org.springframework</groupId> 
<artifactId>spring-context</artifactId> 
<version>3.0.0.RELEASE</version> 
<scope>runtime</scope> 
</dependency> 
</dependencies> 


就 是 这 么 简单 。 要 注意 的 是 ， 如 果 你 在 编译 代码 时 不 需要 使 用 Spring 的 API > MZ 
scope 

元 素 可 以 声明 为 runtime， 这 就 可 以 用 于 典型 的 依赖 注入 用 例 。 在 上 面 的 示例 中 ， 
我 们 使 用 了 Maven 中 央 库 中 的 命名 规约 ， 那 么 它 就 可 以 在 Maven 中 


央 库 或 SpringSource S3 的 Maven 资源 库 中 起 作用 。 要 使 用 S3 的 Maven 资源 库 
(比如 里 程 碑 


版 本 或 开发 快照 ) 版 本 ， 那 就 需要 在 Maven 的 配置 文件 中 明确 地 指定 资源 库 的 位 
置 。 对 于 完整 发 布 版 ， 配 置 如 下 : 


<repositories> 
<repository> 
<id>com.springsource.repository.maven.release</id> 
<url>http://maven.springframework.org/release/</url> 
<snapshots><enabled>false</enabled></snapshots> 
</repository> 
</repositories> 


对 于 里 程 碑 版 本 配置 如 下 : 


<repositories> 
<repository> 
<id>com.springsource.repository.maven.milestone</id> 
<url>http://maven.springframework.org/milestone/</url> 
<snapshots><enabled>false</enabled></snapshots> 
</repository> 
</repositories> 


对 于 开发 快照 版 本 配置 


<repositories> 
<repository> 
<id>com.springsource.repository.maven.snapshot</id> 
<url>http://maven.springframework.org/snapshot/</url1> 
<snapshots><enabled>true</enabled>< /snapshots> 
</repository> 
</repositories> 


要 使 用 SrpingSource 的 EBR 的 话 ， 你 还 需要 一 个 对 依赖 不 同 的 命名 规约 。 名 称 通 
常 很 容 易 去 猜测 ， 比 如 这 个 示例 中 ， 就 是 : 


<dependencies> 
<dependency> 
<grouplId>org.springframework</groupId> 
<artifactId>org.springframework.context</artifactId> 
<version>3.0.0.RELEASE</version> 
<scope>runtime</scope> 
</dependency> 
</dependencies> 


你 也 可 能 需要 明确 地 声明 资源 库 的 位 置 (仅仅 URL 是 重要 的 ) 


<repositories> 
<repository> 
<id>com.springsource.repository.bundles.release</id> 
<url>http://repository.springsource.com/maven/bundles/re 
lease/</url> 
</repository> 
</repositories> 


如 果 你 要 手动 地 去 管理 依赖 ， 在 上 面 这 个 声明 的 资源 库 URL 是 不 可 以 浏览 的 ， 但 
是 它 也 有 一 个 用 户 界面 ， 地 址 是 http://www.springsource.com/repository， 这 可 以 
用 来 搜索 和 下 载 依 赖 。 它 也 有 Maven 和 Ivy 配置 的 代码 片段 ， 你 可 以 复制 下 来 并 
粘贴 到 你 所 使 用 的 工具 中 ， 很 方便 使 用 。 

1.3.1.3 Ivy 依赖 管理 

如 果 你 使 用 |vy 来 管理 依赖 ， 那 么 有 一 些 简 单 的 命名 规约 和 配置 选项 。 

要 配置 Ivy 定位 到 SpringSource EBR 中 ， 需 要 添加 如 下 的 解析 器 元 素 到 你 的 配置 
文件 


ivysettings.xml 中 : 


<resolvers> 
<url name="com.springsource.repository.bundles.release"> 

<ivy pattern="http://repository.springsource.com/ivy/bun 
dles/release 

/ 

[organisation]/[module]/[revision]/[artifact] -[revision 
].[ext]" 

/> 

<artifact pattern="http://repository.springsource.com/iv 
y/bundles/release 

/ 

[organisation]/[module]/[revision]/ [artifact]-[revision 


</url> 
<url name="com.springsource.repository.bundles.external"> 
<ivy pattern="http://repository.springsource.com/ivy/bun 
dles/externa 1/ 
[organisation]/[module]/[revision]/[artifact]-[revision] 
. [ext]" 
/> 
<artifact pattern="http://repository.springsource.com/iv 
y/bundles/externa 1/ 
[organisation]/[module]/[revision]/[artifact ] - [revision] 


</url> 
</resolvers> 


上 面 的 XML 并 不 是 合法 的 格式 ， 因 为 行 太 长 了 一 如 果 你 要 复制 粘贴 ， 那么 要 移 除 
中 部 


url 模式 部 分 结尾 额外 的 行 。 (本 文档 中 已 经 去 除 ) 


一 旦 |vy 配置 ， 那么 添加 依赖 就 很 简单 了 。 只 要 拉 起 在 资源 库 浏览 器 
中 的 捆绑 详细 信息 页 面 ， 你 就 会 发 现 为 你 准备 好 的 Wy 代码 片段 ， 那 么 就 可 以 将 它 
包含 到 你 的 依 


赖 部 分 中 了 。 比 如 (在 ivy.xml 中 ) 
<dependency org="org.springframework" name="org.springframework. 


core" rev="3.0.0.RELEASE" 
conf="compile->runtime"/> 


1.3254 
对 于 Spring 来 说 ， 日 志 是 一 个 非常 重要 的 依赖 ， 因 为 a) 这 是 唯一 强制 ae 


H o b) 开发 人 员 都 会 想 看 到 他 们 所 使 用 的 工具 的 一 些 输出 内 容 ， 而 且 c)Spring 整 
合 了 多 种 实用 工具 ， 它 们 都 会 选择 一 种 日 志 依赖 包 。 应 用 程序 开发 人 员 的 目标 之 一 


就 是 在 核心 位 置 对 整个 应 用 程 序 有 一 个 统一 的 日 志 配置 ， 包 括 对 所 有 的 外 部 组 件 。 
因为 日 志 框 架 有 多 种 选择 ， 那 么 这 就 可 能 有 些 难以 确定 了 。 


Spring 中 强制 的 日 志 依 赖 包 是 Jakarta 的 Commons Logging API (JCL) 。 我 们 对 
Spring 的 编译 是 基于 ICL 的 ， 而 且 我 们 使 扩展 了 Spring Framework 的 类 对 JCL 
包 的 Log 对 象 都 是 可 见 的 。 对 于 用 户 来 说 ， 所 有 Spring 的 版 本 都 使 用 相同 的 日 志 
包 也 是 很 重要 的 : 因为 保留 了 向 后 兼容 的 特性 ， 那 么 迁移 是 很 容易 进行 的 ， 同 理 ， 
扩展 Spring 的 应 用 程序 也 是 这 样 。 我 们 


这 样 做 就 是 使 得 Spring 中 的 模块 明确 地 使 用 基于 commons-logging (JCL 的 典型 
实现 ) 的 日 志 实现 ， 在 编译 时 也 使 得 其 它 模块 都 基于 这 个 日 志 包 。 如 果 你 正在 使 用 
Maven 的 话 ， 同 时 想 知 道 在 哪儿 获取 到 的 commons-logging 依赖 ， 那 就 是 从 
Spring 中 被 称 作 是 spring-core 的 核心 模块 中 获取 的 。 


关于 commons-logging 比较 好 的 做 法 是 你 不 需要 做 其 它 的 步骤 就 可 以 使 应 用 程序 
运 行 起 来 。 它 有 一 个 运行 时 的 查找 算法 ， 在 我 们 都 知道 的 类 路 径 下 寻找 其 它 的 日 志 
框架 ， 并 且 


使 用 Spring 认为 是 比较 合适 的 (或 者 告诉 Spring 你 需要 使 用 的 具体 是 哪 一 个 ) 一 
个 。 如 果 


没有 找到 可 用 的 ， 那 么 你 会 得 到 一 个 来 自 JDK (java.util.logging 或 者 简称 为 JUL) 
本 身 看 起 来 还 不 错 的 日 志 依赖 。 那 么 ， 你 会 发 现在 很 多 时 候 ，Spring 应 用 程序 运 
行 中 会 有 日 志 信 息 打 印 到 控制 台 上 ， 这 点 是 很 重要 的 。 


1.3.2.1 不 使 用 Commons Logging 


不 幸 的 是 ，commons-logging 的 运行 时 查找 算法 对 最 终 用 户 方 便 是 有 些 问 题 的 。 如 
果 我 们 可 以 让 时 光 倒 流 并 让 Spring 从 现在 开始 作为 一 个 新 的 项 目 进 行 ， 那 么 我 们 
会 使 用 不 同 的 日 志 依 赖 。 首 选 的 日 志 依 赖 可 能 就 是 Java 简单 的 日 志 门 面 (SLF4 
J) > SLF4J 也 被 Spring 的 开发 人 员 在 他 们 其 它 应 用 程序 中 的 很 多 工具 所 使 用 。 


关闭 commons-logging 也 很 简单 : 仅仅 要 确认 在 运行 时 ， 它 的 包 不 在 类 路 径 下 就 
可 以 了 。 在 Maven 中 要 去 掉 这 个 依赖 ， 因 为 Spring 依赖 声明 的 时 候 会 带 进来 ， 那 
么 就 需要 这 么 来 进行 。 


<dependencies> 
<dependency> 
<grouplId>org.springframework</groupId> 
<artifactId>spring-context</artifactId> 
<version>3.0.0.RELEASE</version> 
<scope>runtime</scope> 
<exclusions> 
<exclusion> 
<groupiId>commons - logging</groupId> 
<artifactId>commons-logging</artifactId> 
</exclusion> 
</exclusions> 
</dependency> 
</dependencies> 


目前 这 个 应 用 程序 可 能 就 不 能 运行 了 ， 因 为 在 类 路 径 中 已 经 没有 了 JCL API 的 实现 
了 ， 所 以 要 修复 这 个 问题 的 话 ， 就 要 提供 另外 一 种 日 志 的 实现 了 。 在 下 一 节 中 ， 我 
们 来 说 明 如 何 提供 一 个 其 它 的 JCL 的 实现 ， 这 里 ， 我 们 使 用 SLF4J 作为 示例 。 


1.3.2.2 使 用 SLF4J 


SLF4J 是 一 个 整洁 的 日 志 依 赖 ， 在 运行 时 的 效率 也 比 commons-logging 更 高 ， 
为 


SLF4J 使 用 了 编译 时 构建 ， 而 不 是 运行 时 去 查找 其 它 整合 的 日 志 框 架 。 这 也 就 意味 
着 你 可 以 


更 明确 地 在 运行 时 去 做 些 人 什么， 并且 去 声明 或 配置 。SLF4J 为 很 多 通用 的 日 志 框 架 
提供 的 绑 定 ， 所 以 通常 你 可 以 选择 已 有 的 一 个 ， 并 去 绑 定 配置 或 管理 。 


SLF4J 为 很 多 通用 日 志 框 架 提供 绑 定 ， 包 括 JCL， 并 且 也 可 以 反 向 进行 : 桥接 其 它 
的 日 志 框架 和 SLF4J 本 身 。 所 以 如 果 要 在 Spring 中 使 用 SLF4J， 那 么 就 需要 使 用 
SLF4J-JCL 桥 来 代替 


commons-logging *K#i ° RRA BAT > BARA Spring 的 日 志 调 用 就 会 被 翻译 
成 调用 

SLF4J 的 API 了 ， 如 果 在 应 用 程序 中 的 其 它 类 库 使 用 了 原 有 的 API， 那 么 会 有 一 个 
单独 的 地 方 来 进行 配置 和 管理 的 日 志 。 


一 个 常用 的 选择 就 是 桥接 Spring 到 SLF4J API， 之 后 提供 从 SLF4J 到 Log4J 的 明 
确 绑 定 。 你 需要 提供 4 种 依赖 (并 排除 已 经 存在 的 commons-logging 依赖 ) : 桥 
接 工 具 ，SLF4J 的 


API， 绑 定 到 Log4J 的 工具 ， 还 有 Log4J 本 身 的 实现 。 那 么 在 Maven 的 配置 文件 
中 ， 你 就 可 以 这 样 来 做 : 


<dependencies> 

<dependency> 
<groupId>org.springframework</groupId> 
<artifactId>spring-context</artifactId> 
<version>3.0.0.RELEASE</version> 
<scope>runtime</scope> 
<exclusions> 

<exclusion> 
<groupiId>commons- logging</groupId> 
<artifactId>commons-logging</artifactId> 
</exclusion> 

</exclusions> 

</dependency> 

<dependency> 
<groupId>org.slf4j</groupIid> 
<artifactIid>jcl-over-slf4j</artifactId> 
<version>1.5.8</version> 
<scope>runtime</scope> 

</dependency> 

<dependency> 
<grouplId>org.slf4j</groupId> 
<artifactIid>slf4j-api</artifactId> 
<version>1.5.8</version> 
<scope>runtime</scope> 

</dependency> 

<dependency> 
<groupId>org.slf4j</groupId> 
<artifactId>slf4j-1log4j12</artifactiId> 
<version>1.5.8</version> 
<scope>runtime</scope> 

</dependency> 

<dependency> 
<groupiId>log4j</groupId> 
<artifactId>log4j</artifactIid> 
<version>1.2.14</version> 
<scope>runtime</scope> 

</dependency> 

</dependencies> 


这 样 ， 看 起 来 好 像 很 多 依赖 都 需要 日 志 了 。 情 况 确实 是 这 样 ， 但 SLF4J 是 可 选 

的 ， 而 且 它 的 性 能 要 比 含 有 类 加 载 器 问题 的 commons-logging 依赖 好 很 多 ， 尤 其 
是 如 果 你 使 用 了 一 个 严格 限制 的 容器 ， 比 如 OSGI 平台 。 据 称 那 也 会 有 性 能 优势 ， 
因为 绑 定 是 编译 时 进行 的 ， 而 不 是 在 运行 时 。 


另外 ， 在 SLF4J 的 用 户 中 一 个 较为 常见 的 选择 是 使 用 很 少 步骤 ， 同 时 产生 更 少 的 
依赖 ， 那 也 就 是 直接 绑 定 到 Logback 上 。 这 会 去 掉 很 多 额外 的 绑 定 步骤 ， 因 为 
Logback 本 身 直接 实现 了 SLF4J， 这 样 的 话 ， 你 就 仅 需 要 两 个 依赖 的 类 库 ， 
而 不 原先 的 是 四 个 了 (就 是 jcl-over-slf4j 和 logback) 。 如 果 你 也 确实 那么 来 做 
了 ， 你 可 能 还 需要 从 其 它 外 部 依赖 〈 而 不 是 Spring) 中 去 掉 slf4j-api 的 依赖 ， 
为 在 类 路 径 中 只 保留 一 个 APL 的 一 个 版 本 就 行 了 。 


1.3.2.3 使 用 Log4J 


很 多 用 户 出 于 配置 和 管理 的 目的 而 使 用 Log4j 作为 日 志 框 架 。 这 样 也 同样 很 有 效率 
并 且 易于 创建 ， 而 且 ，Log4j 也 是 我 们 事实 上 在 构建 和 测试 Spring 时 ， 和 运行 时 
环境 中 使 用 的 日 志 框 架 。Spring 本 身 也 提供 一 些 工 具 来 配置 和 初始 化 Log4j， 所 
以 ， 在 某 些 模块 中 它 也 提供 了 可 选 的 在 编译 时 对 Log4j 框架 的 依赖 。 


要 让 Log4j 框架 和 默认 的 JCL 依赖 (commons- logging) 同时 起 作用 ， 你 所 要 做 的 
就 是 要 将 Log4j 的 类 库 放 到 类 路 径 下 ， 并 且 提供 配置 文件 (在 类 路径 的 根 路 
径 下 放置 log4j.properties 或 log4j.xml 为 名 的 文件 ) 。 而 对 于 使 用 Maven 的 用 户 
来 说 ， 下 面 的 代码 可 以 是 对 依赖 的 声明 : 


<dependencies> 
<dependency> 
<grouplId>org.springframework</groupId> 
<artifactId>spring-context</artifactId> 
<version>3.0.0.RELEASE</version> 
<scope>runtime</scope> 
</dependency> 
<dependency> 
<groupiId>log4j</groupId> 
<artifactId>log4j</artifactiId> 
<version>1.2.14</version> 
<scope>runtime</scope> 
</dependency> 
</dependencies> 


下 面 是 log4j.properties 打印 到 控制 台 的 日 志 的 配置 示例 : 


log4j.rootCategory=INFO, stdout 


log4j.appender.stdout=org.apache.log4j .ConsoleAppender log4j.ap 
pender.stdout.layout=org.apache.log4j.PatternLayout 1log4j.append 
er.stdout.layout.ConversionPattern=%d{ABSOLUTE} %5p %t %c{2}:%L 

- %m%n 


log4j.category.org.springframework.beans.factory=DEBUG 


运行 时 容器 和 本 地 的 ICL 


很 乡 用 户 在 容器 中 运行 Spring 的 应 用 程序 ， 而 该 容器 本 身 也 提供 了 JCL 的 实现 。 
比如 IBM 的 Webshphere 应 用 服务 器 (WAS) 就 是 这 种 类 型 的 。 这 通常 就 会 引起 
问题 ， 而 不 幸 的 是 没有 什么 解决 的 方法 ; 很 多 情况 下 仅仅 从 应 用 程序 中 去 掉 
commons-logging 依赖 是 不 够 的 。 


我 们 要 清楚 地 认 识 这 一 点 : 这 个 问题 通常 和 JCL 本 身 一 同 报告 出 来 ， 或 者 


是 和 


commons-logging : 而 不 是 绑 定 commons-logging 到 另外 的 框架 (这 里 ， 通 常 是 
Log4J) 。 这 就 可 能 会 引发 问题 ， 因 为 commons-logging 改变 了 它们 在 运行 时 环 
境 里 ， 在 一 些 容器 中 查找 老 版 本 (1.0) 的 方式 ， 而 现在 很 多 人 使 用 的 是 新 版 本 

(1.1) 。Spring 不 会 使 用 任何 不 通用 的 JCL API 部 分 ， 所 以 这 里 不 会 有 问题 ， 但 
是 Spring 本 身 或 应 用 程序 尝试 去 进行 日 志 记 录 ， 你 可 以 发 现 绑 定 到 Log4J 是 不 起 
作用 的 。 


这 种 在 WAS 上 的 情况 ， 最 简单 的 做 法 就 是 颠倒 类 加 载 器 的 层次 (IBM 称 之 
A“parent last”) ， 那 么 就 是 使 应 用 程序 来 控制 ， 而 不 是 容器 来 控制 ICL 的 依赖 。 
这 种 选择 并 不 总 是 开 放 的 ， 但 是 在 公共 领域 中 的 替代 方法 也 有 其 它 的 建议 ， 根 据 确 
切 的 版 本 和 容器 的 特性 集 ， 您 所 要 求 的 效果 可 能 会 有 不 同 。 


分 Spring 3 的 新 特性 


第 2 章 Spring 3.0 的 新 特性 和 增强 


如 果 你 使 用 Spring Framework， 那 么 你 会 看 到 Spring 现在 主要 有 两 个 修订 版 本 : 
一 个 是 在 2006 年 12 月 发 布 的 Spring 2.0， 还 有 一 个 是 在 2007 年 11 月 发 布 的 
Spring 2.5 ° 而 现在 是 第 三 个 版 本 Spring 3.0 了 。 


Java SE 和 Java EE 支持 
Spring Framework 现在 完全 是 基于 Java 5 和 Java 6 版 本 的 。 


此 外 ，Spring 还 兼容 J2EE 1.4 和 Java EE5， 同 时 也 会 介绍 一 些 对 Java EE6 的 先 
期 支持 。 


2.1 Java 5 


框架 的 整体 代码 都 已 经 修订 到 支持 Java 5 的 新 特性 了 ， 比 如 泛 型 ， 可 变 参 数 和 其 
它 的 语 言 方面 的 改进 。 我 们 也 尽 最 大 努力 来 保持 代码 的 向 后 兼容 性 。 现 在 我 们 也 有 
一 致 的 泛 型 集合 和 Map 的 使 用 ， 一 致 的 泛 型 FactoryBean 使 用 ， 还 有 在 Spring 
AOP 的 API 中 对 桥接 方法 的 一 致 性 解决 方案 。 泛 型 的 上 下 文 监听 器 仅仅 自 
动 接收 特定 的 事件 类 型 。 所 有 的 比如 TransactionCallback 和 
HibernateCallback 回调 接口 现在 也 都 声明 为 泛 型 返回 值 。 总 之 ，Spring 核心 代码 
库 都 已 经 为 Java 5 而 进行 修订 和 优化 了 。 


Spring 的 TaskExecutor 抽象 也 已 经 为 和 Java 5 的 java.util.concurrent 的 紧密 整合 
而 更 新 了 。 我 们 现在 为 可 调用 特性 提供 顶级 的 类 的 支持 ， 还 有 ExecutorService £ 
配器 ，ThreadFactory 的 整合 等 。 这 和 JSR-236 (Java EE6 的 并 发 工具 ) RA HE 
是 一 致 的 。 此 外 ， 我 们 还 提供 对 使 用 新 的 @Async 注解 (或 者 EJB 3.1 的 
@Asynchronous 注解 ) 的 异步 方法 调用 的 支持 。 


2.2 改进 的 文档 


Spring 参考 文档 也 有 很 大 的 更 新 ， diag Spring 3.0 的 改进 和 新 特 ， 而 每 一 
项 努 力 都 是 来 保证 在 文档 中 没有 错误 ， 但 是 多 多 少 少 还 会 存在 一 些 错误 。 如 果 你 确 
实 发 现 了 任意 的 错字 或 者 是 严重 的 错误 ， 你 可 以 在 午餐 时 间 把 它们 画 上 圈 ， 然 后 将 


这 些 错误 报告 给 Spring 的 开发 团队 ， 你 可 以 在 JIRA 上 打开 一 个 问题 。 


2.3 新 的 文章 和 教程 

有 很 多 优秀 的 文章 和 教程 来 展示 如 何 开始 使 用 Spring 3 的 新 特性 。 您 可 以 在 
Spring 文档 

页 面 来 阅读 它们 。 

示例 代码 也 已 经 更 新 采用 了 Spring 3 的 新 特性 。 此 外 ， 示 例 代码 也 已 经 从 源码 树 中 


移入 到 了 专用 的 SVN 资源 库 中 。SVN 资 源 库 的 访问 地 址 是 : 
https://anonsvn.springframework.org/svn/spring-samples/ ° 


因此 ， 这 些 示 例 代码 就 不 会 跟 在 Spring 3 的 发 布 包 中 了 ， 需 要 你 从 上 面 提 到 的 资源 
库 中 
分 别 去 下 载 。 而 本 文档 会 继续 引用 一 些 示例 (特别 是 Petclinic) 来 说 明 各 种 特性 。 


要 获取 关于 Subversion (简称 为 SVN) 的 更 多 信息 ， 可 以 参考 SVN 的 项 目 主 页 ， 
地 址 是 : http://subversion.apache.org/ ° 


2.4 新 的 模块 组 织 方式 和 系统 构建 方式 


框架 的 模块 已 经 被 重新 修订 了 ， 现 在 的 组 织 结构 是 : 一 个 源码 分 支 是 一 个 jar 文 
件 : 


org.springframework.aop 
org.springframework.beans 
org.springframework.context 
org.springframework.context.support 
org.springframework.expression 
org.springframework.instrument 
org.springframework.jdbc 
org.springframework.jms 
org.springframework.orm 
org.springframework.oxm 
org.springframework.test 
org.springframework.transaction 
org.springframework.web 
org.springframework.web.portlet 
org.springframework.web.servlet 
org.springframework.web.struts 


注意 : 
原来 的 Spring. jar 文件 包含 了 几乎 所 有 框架 内 容 ， 而 现在 不 再 提供 了 。 


现在 我 们 使 用 新 的 Spring 构建 系统 ， 从 熟知 的 Spring Web Flow 2.0 中 而 来 ， 它 给 
了 我 们 如 下 的 特性 : 


AF Ivy 的 “Spring 构建 ?系统 
一 致 的 开发 过 程 

一 致 的 依赖 管理 

一 致 的 OSGi 清单 生成 


2.5 新 特性 概述 


下 面 列 出 的 是 Spring 3.0 的 新 特性 ， 我 们 在 后 面 章节 的 详细 讲述 中 会 覆盖 到 这 些 特 
性 Lo) 


Spring 表达 式 语言 

loC 增加 /基于 对 Java 的 bean 元 数据 的 支持 

通用 的 类 型 转换 和 字段 格式 化 系统 

对 象 转 XML 映射 功能 (OXM) ， 这 是 从 Spring Web Service 项 目 中 迁 出 的 
全 面 的 REST 支持 

增加 @MVC 

声明 式 的 模型 验证 

先期 对 Java EE 6 的 支持 

RAK AE IE WY RF 


2.5.1 4 Java 5 更 新 的 核心 API 
BeanFactory 接口 尽 可 能 地 返回 该 类 型 bean 的 实例 : 


e T getBean(Class<T> requiredType) 
e T getBean(String name, Class<T> requiredType) 
e Map<String, T> getBeansOfType(Class<T> type) 


现在 ，Spring 的 TaskExecutor 接口 扩展 了 java.util.concurrent.Executor 
e 扩展 的 AsyncTaskExecutor 支持 标准 的 可 调用 特性 
新 的 基于 Java 5 的 转换 API Fe SPI: 


e 无 状态 的 ConversionService 和 转换 器 
e 取代 标准 JDK 的 PropertyEditors 


泛 型 ApplicationListener<E> 


2.5.2 Spring 表达 式 语言 


Spring 引入 了 一 种 表达 式 语 言 ， 这 和 统一 的 EL 在 语法 上 很 相似 ， 但 是 提供 了 很 多 
新 特 性 。 这 种 表达 式 语言 可 以 用 于 定义 基于 XML 和 注解 的 bean， 也 可 以 作为 表达 
式 语言 的 基础 ， 支 持 贯穿 整个 Spring 框架 的 组 合 。 这 些 新 功能 的 详细 内 容 可 以 在 
第 7 章 Spring 表达 式 语言 (SpEL) 中 看 到 。 

Spring 表达 式 语言 被 用 来 为 Spring 社区 提供 一 个 单一 的 ， 支 持 良 好 的 表达 式 语 
言 ， 可 以 用 于 Spring 系列 的 所 有 产品 中 。 它 的 语言 特性 由 Spring 系列 产品 的 所 有 
项 目的 需求 来 共同 驱动 ， 包 括 基于 Eclipse 的 SpringSource Tool 

Suite (SpringSource 组 织 开发 的 工具 套件 ， 译 者 注 ) 代码 完成 支持 工具 的 需求 。 


下 面 是 表达 式 语言 如 何 被 用 于 配置 数据 库 属 性 设置 的 示例 代码 : 


<bean class="mycompany.RewardsTestDatabase"> 
<property name="databaseName" value="#{systemProperties.data 
baseName}" /> 
<property name="keyGenerator" 
value="#{strategyBean.databaseKeyGenerator }"/> 
</bean> 


如 果 你 使 用 注解 来 配置 组 件 ， 那 么 这 个 功能 也 是 可 用 的 : 


@Repository 

public class RewardsTestDatabase { 
@Value("#{systemProperties.databaseName}") 
public void setDatabaseName(String dbName) { ... } 
@Value("#{strategyBean.databaseKeyGenerator}" ) 
public void setKeyGenerator(KeyGenerator kg) { .. } 


2.5.3 控制 反 转 (loC) 容器 


2.5.3.1 基于 Java 的 bean 元 数据 


从 Java Config 项 目 中 引入 的 一 些 核 心 特 性 现在 也 被 加 入 到 Spring Framework 中 
了 。 这 就 是 说 下 面 的 注解 是 直接 被 支持 的 。 


@Configuration 
@Bean 
@DependsOn 
@Primary 

@Lazy 

@Import 
@ImportResource 
@Value 


下 面 是 一 个 Java 类 提供 基本 配置 信息 的 示例 ， 使 用 了 新 的 Java Config 特性 : 


package org.example.config; 

@Configuration 

public class AppConfig { 
private @Value("#{jdbcProperties.url}") String jdbcUrl; 
private @Value("#{jdbcProperties.username}") String username 


private @Value("#{jdbcProperties.password}") String password 


@Bean 
public FooService fooService() { 

return new FooServiceImpl(fooRepository()); 
} 


@Bean 
public FooRepository fooRepository() { 

return new HibernateFooRepository(sessionFactory()); 
} 


@Bean 
public SessionFactory sessionFactory() { 
// 装配 一 个 session factory 
AnnotationSessionFactoryBean asFactoryBean = 
new AnnotationSessionFactoryBean(); asFactoryBean.setDat 
aSource(dataSource()); 
// 其 它 配置 
return asFactoryBean.getObject(); 
} 
@Bean 
public DataSource dataSource() { 
return new DriverManagerDataSource(jdbcUrl, username, pa 
ssword); 


} 
} 


要 让 它 发 挥 作用 ， 你 需要 在 应 用 上 下 文 的 XML 文件 中 添加 如 下 的 组 件 扫描 项 。 


<context:component-scan base-package="org.example.config"/> 
<util:properties id="jdbcProperties" location="classpath:org/exa 
mple/config/jdbc.properties" /> 


或 者 你 可 以 直接 使 用 AnnotationConfigApplicationContext 来 启动 被 
@Configuration 注解 的 类 : 


public static void main(String[] args) { 

ApplicationContext ctx = new AnnotationConfigApplicationCont 
ext (AppConfig. class); 

FooService fooService = ctx.getBean(FooService.class); fooSe 
rvice.doStuff(); 


} 


参考 4.12.2 节 " 使 用 AnnotationConfigApplicationContext 实例 化 Spring 容器 "来 参 
考 关 于 AnnotationConfigApplicationContext 的 全 部 内 容 。 


2.5.3.2 使 用 组 件 定 义 bean 的 元 数据 


@Bean 注解 的 方法 也 可 以 支持 内 部 的 Spring 组 件 。 它 们 贡献 工厂 bean 的 定义 到 
容器 中 。 参考 4.10.4 节 “ 使 用 组 件 定义 bean 的 元 数据 "来 获取 更 多 信息 。 


2.5.4 通用 的 类 型 转换 系统 和 字段 格式 化 系统 


通用 的 类 型 转换 系统 (参考 6.5 节 ) 已 经 引入 了 。 系 统 现在 被 SpEL 使 用 来 进行 类 
型 转 换 ， 当 绑 定 bean 的 属性 值 时 也 会 被 Spring 容器 和 数据 绑 定 器 使 用 。 


此 外 ， 格 式 化 (参考 6.6 节 ) SPI 也 被 引入 了 ， 来 格式 化 字段 值 。 这 个 SPI 对 
JavaBean 的 PropertyEditors 提供 了 简单 的 ， 更 强壮 替代 ， 在 如 Spring MVC 的 窜 
户 端 环境 中 来 使 用 。 


2.5.5 数据 层 


现在 ， 对 象 到 XML 映射 功能 (OXM) 被 从 Spring Web Service 项 目 中 移 到 Spring 
Framework 的 核心 中 。 EE 可 以 在 org. Sengeame wo oxm 包 下 找到 。 关 于 
使 用 OXM 模块 的 更 多 信息 可 以 在 第 15 章 使 用 O/X 映射 器 编组 XML 找到 。 


2.5.6 Web Æ 


对 于 Web 层 来 说 ， 最 令 人 兴奋 的 新 特性 是 对 构建 RESTful Web Service 和 Web 应 
用 程序 的 支持 。 也 有 一 些 新 的 注解 可 以 用 于 任意 的 Web 应 用 程序 。 


2.5.6.1 全 面 的 REST 支持 


对 构建 RESTful 应 用 程序 服务 器 端的 支持 已 经 作为 已 有 的 注解 驱动 的 MVC web 框 
架 而 提 供 了 。 客 户 端的 支持 由 RestTemplate 类 来 提供 ， 和 其 它 的 模板 类 是 相 似 
的 ， 比 如 JdbcTemplate 和 JmsTemplate。 服 务 器 和 客户 端 两 者 的 REST 功能 都 使 
用 HttpConverter 来 在 对 象 和 它们 在 HTTP 请 求 和 响应 代表 之 间 方 便 的 转换 。 


MarshallingHttpMessageConverter 使 用 之 前 提 到 的 对 象 到 XML 映射 功能 。 可 以 
参考 MVC (第 16 章 ) 和 RestTemplate (20.9.1 节 ) 部 分 获取 更 多 信息 。 
2.5.6.2 @MVC 的 增加 

mvc 命名 空间 被 引入 来 大 大 简化 Spring MVC 的 配置 

其 它 如 @CookieValue 和 @RequestHeader 的 注解 也 被 加 入 了 。 参 考 使 用 


@CookieVlue 注解 映射 cookie 值 (16.3.3.9 节 ) 和 使 用 @RequestHeader 注解 映 
射 请 求 头 部 属 性 (16.3.3.10 节 ) 来 获取 更 多 信息 。 


2.5.7 声明 式 的 模型 验证 


一 些 验 证 增强 (6.7 节 ) ， 包 括 JSR303 支持 ， 使 用 Hibernate 校 验 器 作为 默认 提 
供 者 。 


2.5.8 先期 对 Java EE 6 的 支持 


通过 使 用 新 的 @Async 注解 (或 EJB 3.1 的 @Asynchronous 注解 ) 我 们 提供 异步 
方法 调用 。 


JSR 303，JSF 2.0，JPA 2.0 等 
2.5.9 诺 入 式 数 据 库 的 支持 


MELLRE TARAN Java 数据 库 引 擎 (13.8 节 ) 的 方便 支持 ， 包 括 HSQL，H2 
和 Derby。 


第 3 章 Spring 3.1 的 新 特性 和 增强 


在 Spring 3.0 引入 的 支持 之 上 构建 ，Spring 3.1 现在 还 在 开发 中 ， 目 前 Spring 3.1 
M2 才刚 刚 发 布 。 


3.1 新 特性 概述 


(该 部 分 内 容 待 Spring 3.1 GA 发 布 后 翻译 ) 


第 三 部 分 核心 技术 


参考 文档 的 这 一 部 分 涵盖 了 Spring Framework 0 。 这 些 内 容 最 主 
要 的 是 Spring Framework 的 控制 反 转 (loC) 容器 。Spring Framework 的 loC 


容器 的 完全 使 用 是 紧 跟 其 后 的 Spring 的 面向 切面 编程 (AOP) 技术 的 完全 履 盖 。 
Spring Framework 有 它 自己 的 AOP 框架 ， 在 概念 上 很 容易 去 理解 ， 在 Java 企业 
级 编程 中 ， 它 成 功 地 解决 了 80% 的 AOP 需求 的 功能 点 。 


也 提供 了 涵盖 的 Spring 和 AspectJ (目前 最 丰富 的 - 在 功能 方面 一 当然 是 在 Java 
企业 级 空间 中 最 成 熟 的 AOP 实现 ) 的 整合 。 


最 终 ， 通 过 测试 驱动 开发 (test-driven-development，TDD) 的 软件 开发 方法 ， 也 
是 Spring 团队 所 主张 的 ， 所 以 Spring 对 整合 测试 的 支持 也 涵盖 到 了 (ERB 
试 的 最 佳 实践 ) 。Spring 团队 也 发 现 了 loC 的 正确 人 使用， 当然， 这 会 让 单元 和 集成 
测试 更 容易 《setter 方法 的 存在 和 类 的 适当 的 构造 方法 可 以 使 得 它们 很 容易 的 在 测 
试 时 连接 在 一 起 ， 而 不 需要 设立 服务 定位 器 注册 和 诸如 此 类 的 方法 ) 。 这 章 专门 的 
测试 又 往 说 服 你 。 


第 4 章 ，loC 容器 

第 5 章 ， 资 源 

第 6 章 ， 验 证 ， 

第 7 章 ，Spring 表达 式 语言 (SpEL) 

第 8 章 ， 使 用 Spring 进行 面 向 切面 编程 
第 9 Æ > Spring 的 AOP API 

第 10 章 ， 测 试 


B 


KS 


4.1 Spring loC 容器 和 bean 的 介绍 


本 章 涵盖 了 Spring Framework 的 控制 反 转 容器 (loC) [参考 1.1 节 的 背景 ] 原 则 的 
实现 。 OC 也 被 称 为 是 依赖 注入 〈DI) 。 这 是 一 个 对 象 定 义 它 们 依赖 的 过 程 ， 也 就 
是 说 ， 它 们 使 用 的 其 它 对 象 ， 仅 仅 通过 构造 方法 参数 ， 工 厂 方法 参数 或 在 对 象 被 创 
建 后 的 实例 上 设置 的 属性 ， 亦 或 者 是 从 工厂 方法 返回 的 参数 。 之 后 容器 在 它 创建 
bean 的 时 候 注入 那些 依赖 。 这 个 过 程 是 根本 上 的 反 向 ， 因 此 名 称 是 控制 反 转 

(loC) > bean 本 身 控制 实例 化 或 直接 地 使 用 类 的 构 造 来 定位 它 的 依赖 ， 或 者 是 如 
服务 定位 器 模式 的 机 制 。 


org.springframework.beans 和 org.springframework.context 包 是 Spring 
Framework 的 loC 容器 的 基础 。BeanFactory 接口 提供 高 级 的 配置 机 制 ， 可 以 管理 
任意 类 型 的 对 象 。ApplicationContext 是 BeanFactory 的 子 接口 。 它 添加 了 和 
Spring 的 AOP 特性 很 简便 的 整合 ; 消息 资源 处 理 (用 于 国际 化 i18n) ， 事 件 发 

布 ; 应 用 层 特定 的 上 下 文 ， 比如 用 于 Web 应 用 程序 的 WebApplicationContext 。 


总 之 ，BeanFactory 提供 了 配置 框架 和 基本 功能 ， 而 ApplicationContext 添加 了 更 
多 企业 级 开发 特定 的 功能 。ApplicationContext 是 BeanFactory 完整 的 超 集 ， 专 门 
用 于 本 章 ， 来 描述 Spring 的 loC 容器 。 对 于 使 用 BeanFactory 而 不 是 
ApplicationContext 的 更 多 信息 ， 可 以 参考 4.15 节 “BeanFactory”。 


在 Spring 中 ， 对 象 构 成 应 用 程序 的 骨 感 ， 它 们 是 由 Spring 的 loC 容器 管理 的 ， 并 
被 称 为 bean。 一 个 bean 就 是 一 个 实例 化 并 组 装 的 对 象 ， 由 Spring 的 loC 容器 来 
管理 。 否 则 ，bean 就 是 应 用 程序 中 众多 对 象 之 一 。Bean 和 它们 之 间 的 依赖 ， 反 射 
出 由 容器 使 用 的 配置 元 数据 。 


4.2 容器 概述 


org.springframework.context.ApplicationContext 接口 代表 了 Spring 的 loC 容器 ， 
负责 实例 化 ， 配 置 和 装配 上 述 的 bean。 容 器 获得 指示 来 实例 化 茶 对 象 ， 配 置 并 装 
配 ， 这 都 是 通过 读 取 配置 元 数据 实现 的 。 配 置 元 数据 在 XML 中 ，Java 注解 或 Java 
代码 中 来 表示 。 它 允许 你 表达 编写 应 用 程序 的 对 象 ， 还 有 对 象 间 丰富 的 相互 依存 的 


ApplicationContext 接口 的 一 些 实现 使 用 Spring 开 箱 的 支持 。 在 独立 的 应 用 程序 中 
， 通 常 是 来 创建 ClassPathXmlApplicationContext 或 
FileSystemXmlApplicationContext 的 实例 。XML 是 定义 配置 元 数据 的 传统 格式 ， 
你 可 以 指示 容器 使 用 Java 的 注解 或 是 代码 作为 元 数据 的 格式 ， 提 供 少 量 的 XML 
配置 声明 来 开 启 对 这 些 额外 的 元 数据 格式 的 支持 。 


在 很 多 应 用 场景 中 ， 明 确 的 用 户 代 码 不 需要 实例 化 一 个 或 者 多 个 Spring loC 容器 的 
实例 。 比如 ， 在 Web 应 用 场景 中 ， 在 应 用 程序 的 web.xml 中 简单 的 和 八 (左右 ) 行 
样板 J2EE 描述 符 XML 文件 通常 就 够 了 (参考 4.14.4 节 “ 对 Web 应 用 程序 方便 的 
应 用 上 下 文 实例 化 ”) 。 如 果 你 正 使 用 SpringSource 的 工具 套件 ，Eclipse 支持 的 

开发 环境 或 者 是 Spring ROO 这 样 的 样板 配置 ， 就 可 以 容易 地 被 创建 ， 点 几 下 和 鼠标 
或 按键 就 可 以 了 。 


下 图 是 Spring 如 何 工作 的 高 级 别 视图 。 你 的 应 用 程序 类 联合 配置 元 数据 ， 所 以 在 
ApplicationContext 被 创建 和 实例 化 后 ， 就 得 到 了 一 个 完全 配置 的 可 执行 系统 或 程 
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Spring 的 IoC 容器 


4.2.1 配置 元 数据 


正如 上 图 所 示 ，Spring 的 loC 容器 处 理 配 置 元 数据 的 一 种 形式 ; 这 个 配置 元 数据 代 
RT 你 作为 应 用 开发 人 员 是 如 何 告诉 Spring 容器 在 你 的 应 用 程序 中 来 实例 化 ， 配 
置 并 装配 对 象 的 。 


配置 元 数据 传统 上 是 以 直观 的 XML 格式 提供 的 ， 这 是 本 章 的 大 部 分 内 容 使 用 它 来 
传达 Spring loC 容器 关键 概念 和 功能 。 


i 
注意 


基于 XML 的 元 数据 并 不 是 唯一 的 配置 元 数据 格式 。 这 种 配置 元 数据 丰 正 写 入 
时 ，Spring 的 loC 容器 本 身 和 这 种 格式 完全 脱 钓 。 


关于 Spring 容器 使 用 元 数据 格式 的 信息 ， 可 以 参考 : 
基于 注解 的 配置 (4.9 节 ) : Spring 2.5 引入 了 对 基于 注解 元 数据 的 支持 。 


基于 Java 的 配置 (4.12 节 ) : 从 Spring 3.0 开始 ， 很 多 由 Spring JavaConfig 项 
目 提供 的 特 性 称 为 Spring Framework 的 核心 。 因 此 你 可 以 在 应 用 程序 外 部 来 定义 
bean， 使 用 Java 代码 而 不 是 XML 文件 。 要 使 用 这 些 新 的 特性 ， 请 参考 
@Configuration > @Bean ， 


@Import #*@DependsOn 注解 


Spring 配置 典型 的 是 最 少 由 一 个 容器 必须 管理 的 bean 定义 构成 。 基 于 XML 的 配 
置 元 数据 展示 了 这 些 bean 的 配置 是 用 在 顶级 <beans/> 元 素 中 的 <bean/> 元 素 
完成 的 。 


这 些 bean 的 定义 对 应 构成 应 用 程序 中 旦 实 的 对 象 。 比 如 你 定义 的 服务 层 的 对 象 ， 
数据 访问 对 象 (Data Access Object > DAO) ， 表 示 对 象 比 如 Struts 的 Action È 
例 ， 基 础 设置 对 象 比如 Hibernate 的 SesstionFactories，JMS 的 Queues 等 这 些 
典型 的 例子 。 而 不 用 在 容 器 中 定义 细 粒 度 的 领域 模型 对 象 ， 因 为 这 通常 是 由 DAO 
和 业务 逻辑 负责 创 建 并 加 载 的 领域 对 象 。 但 是 你 也 可 以 使 用 Spring 和 AspectJ 整 
合 来 配置 创建 在 loC 容器 控制 之 外 的 对 象 。 参 考 使 用 在 Spring 中 使 用 AspectJ 来 
对 领域 对 象 进行 依赖 EDX (8.8.14) ° 


下 面 的 示例 展示 了 基本 的 基于 XML 的 配置 元 数据 的 结构 : 


<?xml version="1.0" encoding="UTF-8"?> 
<beans xmlns="http://www.springframework.org/schema/beans" 
xmins:xsi=http://www.w3.org/2001/XMLSchema -instance" 
xsi:schemaLocation="http://www.springframework.org/schema/be 
ans 
http: //www.springframework.org/schema/beans/spring -beans-3. 
0.xsd"> 
<bean id="..." class="..."> 
<!-- 这 个 bean 的 合作 者 和 配置 在 这 里 编写 --> 
</bean> 
<bean id="..." class="..."> 
<!-- 这 个 bean 的 合作 者 和 配置 在 这 里 编写 - -> 
</bean> 
<!-- 更 多 的 bean 定 义 在 这 里 编写 --> 
</beans> 


id 属性 是 一 个 字符 串 ， 用 来 标识 定义 的 独立 的 bean。class 属性 定义 了 bean 的 类 
型 ， 需 要 使 用 类 的 完全 限定 名 。id 属性 的 值 指 的 就 是 协作 对 象 。 指 写作 对 象 的 
XML 在 这 个 示例 中 没有 展示 ; 参考 依赖 〈4.4 节 ) 来 获取 更 多 信息 。 


4.2.2 实例 化 容器 


实例 化 Spring 的 loC 容 器 是 很 简单 的 。 定 位 路 径 或 所 有 路 径 提 供给 
ApplicationContext 的 构造 方法 ， 实 际 上 是 表示 资源 的 字符 串 ， 它 就 允许 容器 从 各 
种 外 部 资源 比如 本 地 文件 系统 ，Java 的 CLASSPATH 等 来 加 载 配 置 元 数据 


ApplicationContext context = 

new ClassPathXmlApplicationContext(new String[] {"services.x 
ml" 7 

"daos.xml"}); 


i 

注意 

在 学 习 过 Spring 的 loC 容器 之 后 ， 你 可 能 想 更 多 了 解 Spring 的 Resource 44 
象 ， 这 在 第 5 章 ， 资 源 中 会 描述 ， 它 提供 了 一 个 从 定义 URI 语法 的 位 置 读 取 
输入 流 的 简便 机 制 。 特 别 是 ，Resource 路 径 用 来 构建 应 用 程序 上 下 文 ， 这 会 
在 5.7 节 “应 用 上 下 文 和 资源 路 径 ” 中 来 描述 。 


下 面 的 示例 展示 了 服务 层 代 码 (services.xml) 的 配置 文件 : 


<?xml version="1.0" encoding="UTF-8"?> 

<beans xmlns="http://www.springframework.org/schema/beans" 
xmins:xsi="http://www.w3.org/2001/XMLSchema -instance" 
xSi:schemaLocation="http://www.springframework.org/schema/be 


ans 

http: //www.springframework.org/schema/beans/spring -beans-3. 
O.xsd"> 

<!-- services --> 


<bean id="petStore" 
class="org.springframework.samples.jpetstore.services 
.PetStoreServiceImpL"> 
<property name="accountDao" ref="accountDao"/> 
<property name="itemDao" ref="itemDao"/> 
<!-- 这 个 bean 的 其 它 合作 者 和 配置 在 这 里 编写 - -> 

</bean> 

<!-- 更 多 的 service bean 的 定义 在 这 里 编写 --> 

</beans> 


下 面 的 示例 展示 了 数据 访问 对 象 的 daos.xml 文件 : 


<?xml version="1.0" encoding="UTF-8"?> 
<beans xmlns="http://www.springframework.org/schema/beans" 
xmins:xsi="http://www.w3.org/2001/XMLSchema -instance" 
XSi:schemaLocation="http://www.springframework.org/schema/be 
ans 
http://www.springframework.org/schema/beans/spring -beans-3. 
0.xsd"> 
<bean id="accountDao" 


class="org.springframework.samples.jpetstore.dao.ibat is 
.SqlMapAccountDao"> 


<!-- 这 个 bean 的 其 它 合 作者 和 配置 在 这 里 编写 --> 
</bean> 
<bean id="itemDao" 


class="org.springframework.samples.jpetstore.dao.ibat is 
. SqlMapItemDao"> 


<!-- 这 个 bean 的 其 它 合 作者 和 配置 在 这 里 编写 --> 
</bean> 
<!-- 更 多 数据 访问 对 象 的 定义 在 这 里 编写 --> 
</beans> 


在 上 面 的 示例 中 ， 服 务 层 代码 由 类 PetStoreServicelmpl 和 两 个 基于 iBatis (iBatis 
现 已 更 名 为 MyBatis， 译 者 注 ) 对 象 /实体 映射 框架 的 数据 访问 对 象 
SqlMapAccountDao 和 SqiMapltemDao 构成 。property 的 name 元 素 指 的 是 
JavaBean 的 属性 名 ， 而 ref 元素 指 的 是 其 它 bean 定义 的 名 称 。id 和 ref 元 素 之 间 
的 这 种 联系 表示 了 两 个 协作 对 象 的 依赖 关系 。 要 了 解 更 多 配置 对 象 依赖 的 信息 ， 可 
以 参考 依赖 (44 节 ) 。 


4.2.2.1 处 理 基于 XML 的 配置 元 数据 


跨越 多 个 XML 文件 中 定义 bean 是 很 有 用 的 。 通 常 每 个 独立 的 XML 配置 文件 代表 
了 一 个 逻辑 层 或 架构 中 的 一 个 模块 。 


你 可 以 使 用 ApplicationContext 的 构造 方法 从 所 有 的 XML 文件 片段 中 来 加 载 
bean。 这 个 构造 方法 可 以 接收 多 个 Resource 位 置 ， 这 在 之 前 的 部 分 都 已 经 看 到 
了 。 另 外 ， 可 以 使 用 一 个 或 多 个 <import/> 元 素来 从 另外 的 一 个 或 多 个 文件 中 加 
载 bean。 比 如 : 


<beans> 
<import resource="Services.xml"/> 
<import resource="resources/messageSource. xmL"/> 
<import resource="/resources/themeSource. xmL"/> 


<bean id="beani" class="..."/> 
<bean id="bean2" class="..."/> 
</beans> 


在 这 个 示例 中 ， 外 部 的 bean 通 过 三 个 文件 来 加 载 ， 分 别 是 services.xml 
，messageSource.xml 和 themeSource.xml。 上 所 有 的 位 置 路 径 都 是 相对 于 该 引用 
文件 的 ， 所 以 service.xml 必须 在 和 引用 文件 相同 路 径 中 或 者 是 类 路 径 下 ， 
而 messageSource.xml 和 themeSource.xml 必须 是 在 位 于 引用 文件 下 一 级 
的 resources 路 径 下 。 正 如 你 看 到 的 ， 前 部 的 斜 杠 被 忽略 了 ， 这 是 由 于 路 径 都 是 相 
对 的 ， 最 好 就 不 用 斜 线 。 文 件 的 内 容 会 被 引入 ， 包 括 顶 级 的 <beans/> 元 素 ， 根 
据 Spring 的 Schema 或 DTD， 它 必须 是 有 效 bean 定义 的 XML 文件 。 


į) 


在 父 目 录 中 使 用 相对 路 径 “../" 来 引用 文件 ， 这 是 可 能 的 ， 但 是 不 推荐 这 么 做 。 这 
么 做 了 会 创建 一 个 文件 ， 它 是 当前 应 用 程序 之 外 的 一 个 依赖 。 特别 是 ， 这 种 引 
用 对 于 “classpath : "的 URL ( rite > “classpath:../service.xml”) 是 不 推荐 的 ， 
运行 时 的 解析 过 程 会 选择 “最 近 的 "类 路 径 根 目录 并 且 会 查看 它 的 父 目录 。 类 路 
径 配 置 的 修改 可 能 会 导 致 去 选择 一 个 不 同 的 ， 不 正确 的 目录 。 你 也 可 以 使 用 
资源 位 置 的 完全 限定 名 来 代替 相对 路 径 : Hite >» “file: C:/config /services.xml” 
或 “classpath:/config/services.xml”。 这 样 的话 ， 要 注意 你 会 契合 应 用 程序 的 配 
置 到 指定 的 绝对 路 径 。 对 于 绝对 路 径 ， 一 般 最 好 是 保持 一 个 间接 的 使 用 ， 比 如 
通过 占 位 符 "${...， 这 会 基于 运行 时 环境 的 JVM 系统 属性 来 解决 。 


4.2.3 使 用 容器 
ApplicationContext 是 能 维护 不 同 的 bean 和 它们 依赖 注册 的 高 级 工厂 接口 。 使 用 
T getBean(Stringname, Class<T> requiredType) 方法 你 可 以 获取 bean 的 实 
例 o 
ApplicationContext 允许 你 读 取 bean 并 且 访 问 它 们 ， 如 下 所 示 : 


// 创建 并 配置 bean 
ApplicationContext context = 
new ClassPathXmlApplicationContext(new String[] {"services.x 
ml", 
"daos.xml"}); 
// 获取 配置 的 实例 
PetStoreServiceImpl service = context.getBean("petStore", PetSto 
reServiceImpl.class)j; 
// 使 用 配置 的 实例 
List userList service.getUsernameList(); 


使 用 getBean() 方 法 来 获取 bean 的 实例 。ApplicationContext 接口 有 一 些 其 它 方法 
来 获取 bean， 但 最 好 应 用 程序 代码 不 使 用 它们 。 事 实 上 ， 应 用 程序 代码 应 该 没有 
getBean() 方 法 的 调用 ， 那 么 就 没有 对 Spring API 的 依赖 了 。 比 如 ，Spring 和 Web 
框架 整 SNM > RET MAF Web 框架 类 库 的 依赖 注入 ， 不 如 控制 器 和 JSF 管理 的 
bean。 


4.3 Bean 概述 
Spring n loC 容器 管理 一 个 或 多 个 bean。 这 些 bean 通过 提供 给 容器 的 配置 元 数 
据 被 创 建 出 来 ， 比 如 ， 在 XML 中 的 <bean/> 定义 的 形式 。 


在 容器 本 身 ， 这 些 bean 代表 了 BeanDefinition 对 象 ， 它们 包含 (在 其 它 信息 中 ) 
下 列 元 数据 : 


包 的 类 限定 名 : 就 是 这 些 bean 4) AsE LMA o 


bean 的 行为 配置 元 素 ， 这 表示 了 bean 在 容器 中 (范围 ， 生 命 周期 回调 等 等 ) 应 该 
是 怎 样 的 行为 。 


对 其 它 bean 的 引用 ， 这 是 该 bean 工作 所 需要 的 ; 这 些 引 用 通常 被 称 为 合作 者 或 
依赖 。 


在 新 被 创建 的 对 象 中 的 其 它 配 置 设 置 ， 比 如 ， 管 理 连 接 池 的 bean 中 使 用 的 连接 数 
或 连 接 池 限制 的 大 小 。 


元 数据 翻译 成 一 组 属性 集合 来 构成 每 一 个 bean 的 定义 。 
表 4.1 bean 定义 





属性 解释 章节 
class 4.3.2 节 “实例 化 bean” 
name Ad Dean 
scope 4.5 节 ，“bean 的 范围 ” 
constructor arguments 4.4.1 Fo “URPMIEA” 
properties 44.1 $ > “RIEA?” 
autowiring mode MAE R ER EFA 
lazy-initialization mode 4.4.4 节 > “RWA bean” 
initialization method 4.6.1.1 节 ，“ 初 始 化 回调 ” 
descruction method 4.6.1.2 $ > "销毁 回调 ” 


此 外 ，bean 的 定义 还 包含 如 何 创建 特定 bean 的 信 息 ，ApplicationContext 的 实现 
类 允许 用 户 将 容器 外 部 创建 的 已 有 对 象 的 注册 。 这 可 以 通过 getBeanFactory() 方 法 
访问 ApplicationContext 的 BeanFactory 来 完成 ， 它 会 返回 BeanFactory 的 实 
现 类 DefaultListableBeanFactory 。 DefaultListableBeanFactory 通过 
registerSingleton(..) 和 registerBeanDefinition(..) 方 法 来 支持 这 种 注册 。 而 典型 的 应 
用 程序 只 和 通过 元 数据 定义 的 bean 来 工作 。 


4.3.1 命名 bean 


每 个 bean 有 一 个 或 者 多 个 标识 符 。 这 些 标识 符 必须 在 托管 bean 的 容器 内 唯一 。 
通常 一 个 bean 只 有 一 个 标识 符 ， 但 如 果 它 需要 多 个 的 话 ， 其 它 的 可 以 被 认为 是 别 
2s 


在 基于 XML 的 配置 元 数据 中 ， 你 可 以 使 用 id 和 /或 name 属性 来 指定 bean 的 标识 
符 。id 属性 允许 你 指定 一 个 准确 的 id。 按照 管理 这 些 名 称 是 字母 和 数字 

(‘myBean’ > ‘fooService’ 等 ) ， 但 是 可 能 是 特殊 字符 。 如 果 你 想 为 bean 引入 别 
名 ， 你 也 可 以 在 name 属性 中 来 指定 ， 


通过 过 号 (,) ， 分 号 (;) 或 空格 来 分 隔 。 作 为 对 历史 的 说 明 ， 在 Spring 3.1 版 之 
前 ，id 属性 是 xsd:ID 类 型 ， 只 限定 为 字符 。 在 3.1 版 本 中 ， 现 在 是 Xxsd:string 类 
型 了 。 要 注意 bean 的 id 的 唯一 性 还 是 被 容器 所 强制 的 ， 但 是 对 于 XML 处 理 器 却 
不 是 。 


当然 你 也 可 以 不 给 bean 提供 name 或 id。 如 果 没 有 提供 明确 的 name 或 id， 那 么 
容器 会 为 这 个 bean 生成 一 个 唯一 的 名 称 。 然 而 ， 如 果 你 想 通 过 名 称 来 参考 这 个 
bean > RA TA 使 用 ref 元 素 或 者 是 服务 定位 器 (4.15.2 节 ) 风格 的 查找 ， 你 必须 
提供 一 个 名 称 。 不 提供 名 称 的 动机 是 和 使 用 内 部 bean (4.4.2.3 7) 或 自动 装备 合 
作者 (4.4.5 节 ) 相关 的 。 


Bean 的 命名 约定 


该 约定 是 用 于 当 命 名 bean 时 ， 对 实例 字段 名 称 的 标准 Java 约定 。 也 就 是 说 ， 
bean 的 名 称 以 小 写字 母 开 始 ， 后 面 是 驼峰 形式 的 。 这 样 的 命名 可 以 是 (没有 引 


Aas 


号 ) ‘accountManager’ > ‘accountService’ > ‘userDao’ > ‘loginController’ 等 。 


一 致 的 命名 bean 可 以 使 你 的 配置 信息 易于 阅读 和 理解 ， 如 果 你 使 用 Spring 的 
AOP ， 当 应 用 通知 到 一 组 相关 名 称 的 bean 时 ， 它 会 给 你 很 大 的 帮助 。 


4.3.1.1 在 bean 定义 外 面 起 别名 


在 bean 定义 的 本 身 ， 你 可 以 为 bean 提供 多 于 一 个 的 名 称 ， 使 用 一 个 由 id 属性 或 
name 属性 中 的 任意 名 称 数 指定 的 名 称 组 合 。 这 些 名 称 对 于 同一 个 bean 来 说 都 是 
相等 的 别名 ， 在 一 些 情 况 下 ， 这 是 很 有 用 的 ， 比 如 在 应 用 程序 中 允许 每 个 组 件 参考 
一 个 共同 的 依赖 ， 可 以 使 用 为 组 件 本 身 指定 的 bean 的 名 称 。 


然而 ， 在 bean 定义 时 指定 所 有 的 别名 是 不 够 的 。 有 事 可 能 想 在 任意 位 置 ， 为 一 个 
bean 引入 一 个 别名 。 这 在 大 型 系统 中 是 很 常见 的 例子 ， 其 中 的 配置 信息 是 分 在 每 
个 子 系统 中 的 ， 每 个 子 系统 都 有 它 自己 的 对 象 定义 集合 。 在 基于 XML 的 配置 元 数 
据 中 ， 你 可 以 使 用 <alias/> 元 素来 完成 这 项 工作 。 


<alias name="fromName" alias="toName"/> 


在 这 个 示例 中 ， 在 相同 容器 中 的 名 称 为 fomName 的 bean， 在 使 用 过 这 个 别名 定 
义 后 ， 也 可 以 使 用 toName 来 指引 。 


比如 ， 在 子 系统 的 配置 元 数据 中 ，A 可 能 要 通过 名 称 ‘subsystemA-dataSource’ 来 指 
向 数据 源 。 为 子 系统 B 的 配置 元 数据 可 能 要 通过 名 称 ‘subsystemB-dataSource’ 来 
指向 数据 源 。 


当 处 理 使 用 了 这 两 个 子 系统 的 主 程序 时 ， 主 程序 要 通过 名 称 'myApp-dataSource' 来 
指向 数 据 源 。 那 么 就 需要 三 个 名 称 指向 同一 个 对 象 ， 那 么 就 要 按照 下 面 的 别名 定义 
来 进行 添加 


MyApp 的 配置 元 数据 : 


<alias name="subsystemA-dataSource" alias="subsystemB-dataSource 
uS 
<alias name="subsystemA-dataSource" alias="myApp-dataSource" /> 


现在 每 个 组 件 和 主 程序 都 可 以 通过 一 个 唯一 的 保证 不 冲突 的 名 称 来 还 有 其 它 任意 定 
义 (更 有 效 地 是 创建 命名 空间 ) 来 参照 数据 源 了 ， 当 然 它 们 参照 的 是 同一 个 
a o 


4.3.2 实例 化 bean 


bean 的 定义 信息 本 质 上 是 创建 一 个 或 多 个 对 象 的 方 子 。 当 需要 一 个 bean 时， 容器 
查找 名 的 bean， 并 且 使 用 由 bean 定义 信息 封装 的 配置 元 数据 
来 创建 (或 获得 ) 一 个 真实 的 对 象 。 


如 果 你 使 用 基于 XML 的 配置 元 数据 ， 象 所 指定 的 类 型 (或 
类 ) 是 <bean/> TURF class 属性 。 这 个 class 属性 ， 是 BeanDefinition 实例 内 
部 的 cla ss 属性 ， 通 常 是 强制 要 有 的 。 ， 可 以 参考 4.3.2.3 节 ，“ 使 用 实 
例 的 工厂 方法 来 实例 化 ?和 4.7 F > “Bean 定义 的 继承 ") 你 可 以 以 两 种 方法 之 一 来 
使 用 class 属性 : 


典型 的 是 ， 指 定 要 被 构造 的 bean 类 ， 容 器 本 身 直接 通过 反射 调用 它 的 构造 方法 来 
创建 bean， 也 就 是 和 Java 代码 中 使 用 new 操作 符 是 相同 的 。 


指定 包含 static 工厂 方法 的 丨 实 的 类 ， i | 建 对 象 ， 在 一 些 不 太 常见 的 情 
HES ， 容器 会 调用 类 的 static 工厂 方法 来 创建 bean。 从 调用 static 工厂 方法 返回 的 
对 象 类 型 可 能 是 和 另外 一 个 类 完全 B on 


内 部 类 名 称 


如 果 你 想 为 static RAM KAA bean， 你 需要 使 用 内 部 类 的 二 进 制 名 称 。 比如 ， 
如 果 在 com.example 包 下 有 一 个 Foo 类 ,而 这 个 Foo 类 有 一 个 static 的 内 部 类 
Bar， 那 么 在 定义 bean 时 'class' 属 性 的 值 就 会 是 .… 


com.example.Foo$Bar 
请 注意 名 称 中 $ 符 号 的 使 用 ， 用 来 从 外 部 类 名 中 分 隔 内 部 类 名 。 


4.3.2.1 使 用 构造 方法 实例 化 


当 你 使 用 构造 方法 来 创建 bean 时 ， 所 有 普通 的 类 的 使 用 都 和 Spring 兼容 。 也 就 是 

说 ， 开 发 中 的 bean 不 需要 实现 任何 特定 的 接口 或 以 特定 的 方式 来 编码 。 仅 简单 指 

定 bean 的 类 就 足够 了 。 但 基于 你 使 用 的 是 什么 类 型 的 loC， 就 可 能 需要 一 个 默认 
( 空 的 ) 构造 方法 。 


Spring 的 loC 容器 可 以 虚拟 地 管理 任意 的 你 想 让 它 管理 的 类 ; 而 不 仅仅 限于 管理 昌 
正 的 JavaBean。 很 多 Spring 用 户 喜欢 在 容器 中 使 用 有 轩 认 《无 参数 ) 构造 方法 和 
在 其 后 有 适当 setter 和 getter X449 HE JavaBean。 你 也 可 以 在 容器 中 使 用 很 多 
异样 的 ， 非 bean 样式 的 类 。 比 如 ， 需 要 使 用 遗留 的 连接 池 ， 但 是 它 没有 符合 
JavaBean 的 规范 ，Spring 也 能 照样 管理 它 。 


基于 XML 的 配置 元 数据 ， 你 可 以 如 下 来 定义 bean : 


<bean id="exampleBean" class="examples.ExampleBean"/> 
<bean name="anotherExample" class="examples.ExampleBeanTwo"/> 


关于 提供 构造 方法 参数 (如 果 需 要 ) 和 在 对 象 被 构造 后 ， 设 置 对 象 实例 属性 机 制 的 
详情 ， 请 参考 4.4.1 节 依 赖 注入 。 


4.3.2.2 使 用 静态 工厂 方法 来 实例 化 


当 使 用 静态 工厂 方法 来 定义 bean 的 时 候 ， 可 以 使 用 class 属性 来 指定 包含 static 
工厂 方法 的 类 ， 而 名 为 factory-method 的 属性 来 指定 静态 方法 。 你 应 该 调用 这 个 
方法 (还 可 以 有 可 选 的 参数 ) 并 返回 一 个 实际 的 对 象 ， 随 后 将 它 视 为 是 通过 构造 方 
法 创建 的 一 样 。 在 遗留 代码 中 ， 这 样 定义 bean 的 使 用 方式 之 一 是 调用 static 工 
is 


下 面 bean 的 定义 指定 了 要 通过 调用 工厂 方法 生成 的 bean。 这 个 定义 没有 指定 返回 
对 象 的 类 型 (X) ， 仅 仅 是 包含 工厂 方法 的 类 。 在 本 例 中 ，createlnstance() 方 法 
必须 是 静 态 方法 。 


<bean id="clientService" class="examples.ClientService" factory- 
method="createInstance"/> 
public class ClientService { 
private static ClientService clientService = new 
ClientService(); 
private ClientService() {} 
public static ClientService createInstance() { 
return clientService; 


} 


关于 提供 (可 选 的 ) 参数 到 工厂 方法 并 在 对 象 由 工厂 返回 后 设置 对 象 实 例 属 性 的 机 
制 详 情 ， 请 参考 4.4.2 节 深 入 依赖 和 配置 。 


4.3.2.3 使 用 实例 工厂 方法 来 实例 化 


和 使 用 静态 工厂 方法 (4.3.2.2 节 ) 实例 化 相似 ， 使 用 实例 工厂 方法 实例 化 是 要 调用 
容器 中 已 有 bean 的 一 个 非 静 态 的 方法 来 创建 新 的 bean。 要 使 用 这 个 机 制 ， 请 把 
class 属性 留 空 ， 但 在 factory-bean 属性 中 指定 当前 (或 父 /祖先 ) 容器 中 bean 的 
名 字 ， 该 bean 要 包含 被 调用 来 创建 对 象 的 实例 方法 。 使 用 factory-method 方法 来 
设置 工厂 方法 的 名 称 。 


<!-- 工厂 bean， 和 包含 名 为 createInstance( ) 的 方法 --> 
<bean id="serviceLocator" class="examples.DefaultServiceLocator" 
= 
<!-- Alocator bean 注 入 任意 需要 的 依赖 --> 
</bean> 
<!-- 通过 工厂 bean 来 创建 的 bean --> 
<bean id="clientService" 
factory-bean="serviceLocator" 
factory-method="createClientServiceInstance"/> 
public class DefaultServiceLocator { 
private static ClientService clientService = new 
ClientServiceImpl(); 
private DefaultServiceLocator() {} 
public ClientService createClientServiceInstance() { 
return clientService; 
} 


一 个 工厂 类 也 可 以 有 多 于 一 个 工厂 方法 ， 比 如 下 面 这 个 : 


<bean id="serviceLocator" class="examples.DefaultServiceLocator" 
= 
<!--Alocator bean 注 入 任意 需要 的 依赖 --> 
</bean> 
<bean id="clientService" 
factory-bean="serviceLocator" 
factory-method="createClientServiceInstance"/> 
<bean id="accountService" factory-bean="ServiceLocator" 
factory-method="createAccountServiceInstance"/> 
public class DefaultServiceLocator { 
private static ClientService clientService = new 
ClientServiceImpl(); 
private static AccountService accountService = new 
AccountServiceImpl(); 
private DefaultServiceLocator() {} 
public ClientService createClientServiceInstance() { 
return clientService; 


public AccountService createAccountServiceInstance() { 
return accountService; 
} 


这 个 方法 展示 了 工厂 bean 本 身 可 以 通过 依赖 注入 (DI) 被 管理 和 配置 。 请 参考 
4.4.2 节 


深入 依赖 和 配置 。 注意 在 Spring 文档 中 ， 工 厂 bean 指 的 是 在 Spring 容 
的 bean， 可 以 通过 实例 (4.3.2.3 节 ) 或 静态 (4.3.2.2 节 ) 工厂 方法 来 创 
与 此 相反 的 是 ，FactoryBean (注意 大 小 写 ) 指 的 是 Spring 特定 的 
FactoryBean (4.8.3 节 ) 


器 中 配 
建 对 象 


° Es 


4.4 依赖 


典型 的 企业 级 应 用 程序 不 是 由 单独 对 象 〈 或 Spring 中 的 bean) 构成 的 。 尽 管 最 简 

单 的 应 用 程序 有 一 些 对 象 协同 工作 来 表示 终端 用 户 所 看 到 的 连贯 的 应 用 。 下 一 节 会 

解释 如 何 去 为 完全 实现 的 应 用 程序 定义 一 组 独立 的 bean， 其 中 对 象 间 相互 协作 来 
达到 目标 。 


4.4.1 依赖 注入 


依赖 注入 (D1) 是 对 象 定义 它们 依赖 的 过 程 ， 也 就 是 说 ， 要 和 它们 协同 工作 其 它 对 
象 ， 仅 仅 可 以 通过 构造 方法 参数 ， 工 厂 方法 参数 ， 或 者 是 在 工厂 方法 返回 的 对 象 或 
被 构造 好 后 ， 


为 对 和 象 实例 设置 的 属性 。 容 器 当 创建 好 bean， 随 后 就 会 注入 那些 依赖 。 这 个 过 程 
从 根本 上 来 说 是 反 向 的 ， 因此 全 命名 为 控制 反 转 (loC) > bean 本 身 直接 使 用 构造 
好 的 类 或 服务 定位 器 模式 来 控制 实例 或 它 的 依赖 的 所 在 位 置 。 


应 用 了 DI 原则 ， 代 码 就 干净 多 了 ， 当 为 对 象 提供 它们 依赖 的 时 候 ， 解 看 是 很 有 效 
率 的 。 


对 象 不 再 去 检查 它 的 依赖 ， 也 不 需要 知道 位 置 或 依赖 的 类 。 因 此 ， 类 就 很 容易 被 测 
试 ， 特 别 是 当 依 赖 是 接口 或 抽象 基 类 的 时 候 ， 这 允许 在 单元 测试 中 使 用 stub 或 
mock 的 实现 类 。 


DI 存在 两 种 主要 的 方式 ， 基 于 构造 方法 的 依赖 注入 (4.4.1.1 节 ) 和 基于 setter 方 
法 的 依赖 注入 (4.4.1.2 节 ) ° 


4.4.1.1 基于 构造 方法 的 依赖 注入 


基于 构造 方法 的 依赖 注入 是 容器 调用 构造 方法 和 一 组 参数 完成 的 ， 每 个 都 表示 着 一 
个 依赖。 使 用 特定 的 参数 来 调用 static 工厂 方法 构造 bean 基本 也 是 相同 的 ， 这 种 
说 法 把 给 构 造 方法 的 参数 和 给 static 工厂 方法 的 参数 相 类 似 。 下 面 的 示例 展示 了 一 
个 仅 使 用 构造 方 法 进行 依赖 注入 的 饿 类 。 注 意 这 个 类 没有 什么 特殊 之 处 ， 就 是 一 个 
POJO 而 且 没 有 对 容器 特定 接口 ， 基 类 或 注解 的 依赖 。 


public class SimpleMovieLister { 
// SimpleMovieLister *MovieFinderA fk% 
private MovieFinder movieFinder; 
// 这 个 构造 方法 使 得 Spring 容器 可 以 "注入 ， MovieFinder 
public SimpleMovieLister(MovieFinder movieFinder) { 
this.movieFinder = movieFinder; 


} 
// 业务 逻辑 就 可 以 "使 用 "注入 的 MovieFinder 了 ， 代 码 就 省 略 了 , , ， 


构造 方法 参数 解析 


构造 方法 参数 解析 匹配 使 用 参数 的 类 型 。 如 果 在 bean 的 构造 方法 参数 不 存在 潜在 
的 歧义 ， 那 么 当 bean 被 实例 化 的 时 候 ， 定 义 的 构造 方法 参数 的 顺序 就 是 被 提供 到 
适当 构造 方法 参数 的 顺序 。 请 看 下 面 的 类 : 


package x.y; 
public class Foo { 
public Foo(Bar bar, Baz baz) { 
YL ier 
} 


没有 潜在 的 歧义 存在 ， 假 设 Bar 和 Baz 类 没有 继承 关系 。 因 此 下 面 的 配置 就 可 以 使 
用 了 ， 而 且 并 不 需要 明确 地 在 <constructor-arg/> 元 素 中 去 指定 构造 方法 参数 
的 索引 和 / 或 类 型 。 


<beans> 
<bean id="foo" class="x.y.Foo"> 
<constructor-arg ref="bar"/> 
<constructor-arg ref="baz"/> 
</bean> 
<bean id="bar" class="x.y.Bar"/> 
<bean id="baz" class="x.y.Baz"/> 
</beans> 


当 另 外 一 个 bean 被 引用 时 ， 类 型 是 明确 的 ， 那 么 匹配 就 能 成 功 〈 前 面 示例 中 也 是 
这 样 的 ) 。 当 使 用 简单 类 型 时 ， 比 如 <value>true<value> ，Spring 不 能 决定 值 
的 类 型 ， 所 以 没有 帮助 是 不 能 匹配 的 。 看 下 面 的 示例 : 


package examples; 
public class ExampleBean { 
// tt IME Ry HK 
private int years; 
// ker FH’ HA PRN SR 
private String ultimateAnswer; 
public ExampleBean(int years, String ultimateAnswer) { 
this.years = years; 
this.ultimateAnswer = ultimateAnswer; 


构造 方法 参数 类 型 匹配 


在 上 面 的 情形 下 ， 如 果 你 使 用 type 属性 明确 地 为 构造 方法 参数 指定 类 型 的 话 ， 容 
器 可 以 进行 匹配 简单 的 类 型 。 比 如 : 


<bean id="exampleBean" class="examples.ExampleBean"> 
<constructor-arg type="int" value="7500000"/> 
<constructor-arg type="java.lang.String" value="42"/> 
</bean> 


构造 方法 参数 索引 
使 用 index 属性 来 指定 明确 的 构造 方法 参数 索引 。 比 如 : 


<bean id="exampleBean" class="examples.ExampleBean"> 
<constructor-arg index="0" value="7500000"/> 
<constructor-arg index="1" value="42"/> 

</bean> 


此 外 ， 为 了 解决 多 个 简单 值 的 歧义 ， 如 果 构 造 方法 有 两 个 相同 类 型 的 参数 时 ， 指 定 
所 以 可 以 解决 歧义 。 注 意 索 引 是 基于 0 开始 的 。 


构造 方法 参数 名 称 
在 Spring 3.0 中 ， 你 也 可 以 使 用 构造 方法 参数 名 称 来 消除 歧义 : 


<bean id="exampleBean" class="examples.ExampleBean"> 
<constructor-arg name="years" value="7500000"/> 
<constructor-arg name="ultimateanswer" value="42"/> 
</bean> 


BLIGE BARAK FPA AAT A > RAG sb A Ae A a AO RAER — 82 IE >» ABAE Spring 
AT 以 从 构造 方法 中 来 查找 参数 。 如 果 没 有 和 调试 标识 〈 或 不 想 ) AMIE? MA 
可 以 使 用 JDK 的 注解 @ConstructorProperties 来 明确 构造 方法 参数 。 那 么 示例 代 
码 就 如 下 所 示 : 


package examples; 
public class ExampleBean { 
// 忽略 属性 
@ConstructorProperties({"years", "ultimateAnswer"}) 
public ExampleBean(int years, String ultimateAnswer) { 
this.years = years; 
this.ultimateAnswer = ultimateAnswer; 


4.4.1.2 基于 setter 方法 的 依赖 注入 


基于 setter 方法 的 依赖 注入 由 容器 在 调用 过 无 参数 的 构造 方法 或 无 参数 的 static 工 
厂 方法 来 实例 化 bean 之 后 ， 再 调用 bean 的 setter 方法 来 完成 的 。 


下 面 的 示例 展示 了 一 个 仅仅 能 使 用 纯 setter 方法 进行 依赖 注入 的 类 。 这 是 一 个 常见 
的 Java 类 ， 是 一 个 没有 依赖 容器 指定 的 接口 ， 基 类 或 注解 的 POJO 。 


public class SimpleMovieLister { 
// SimpleMovieLister 4MovieFinder 4% tk #i 
private MovieFinder movieFinder; 
// setter 方 法 可 以 让 Spring 容器 来 "注入 'MovieFinder 
public void setMovieFinder(MovieFinder movieFinder) { 
this.movieFinder = movieFinder; 


} 
// 站 正 "使 用 /注入 的 MovieFinder 的 业务 逻辑 代码 被 省 略 了 ., ， 


ApplicationContext 对 它 管理 的 bea n 支持 基于 构造 方法 和 setter 方法 的 依赖 注 
A o 


也 支持 在 一 些 依 赖 已 经 通过 构造 方法 注入 之 后 再 进行 setter 方 法 注 
A °> 以 


BeanDefinition 形式 来 配置 依赖 ， 使 用 PropertyEditor 实例 将 属性 从 一 种 形式 格式 
化 到 另 一 种 。 但 很 多 Spring 的 用 户 不 直接 (编程 时 ) 使 用 这 些 类 ， 而 是 使 用 XML 
文件 来 定 义 ， 之 后 会 在 内 部 转换 这 些 类 的 实例 ， 需 要 加 载 整 个 Spring loC 容器 的 
实例 。 


基于 构造 方法 还 是 setter 方法 进行 依赖 注入 ? 因为 你 可 以 将 二 者 混淆 ， 那 么 对 于 基 
于 构造 方法 或 是 setter 方法 的 依赖 注入 ， 有 一 个 很 好 的 规则 就 是 为 强制 依赖 使 用 构 
造 方法 参数 ， 而 对 于 可 选 参 数 使 用 setter 方法 。 要 注意 在 setter 方法 上 使 用 注解 
@Required (4.9.1 节 ) > TAT setter 方法 所 需 的 依赖 。 


Spring 团队 通常 主张 使 用 setter 方法 注入 ， 因 为 大 量 的 构造 方法 参数 会 使 程序 变 得 
非 常 策 拙 ， 特 别 是 当 属性 为 可 选 的 时 候 。Setter 方法 会 让 该 类 的 对 象 今后 适合 于 重 
新 配置 或 重新 注入 。 通 过 JMX Mbean (第 23 章 ) 来 管理 就 是 一 个 令 人 关注 的 用 
例 o 


一 些 人 纯粹 赞成 构造 方法 注入 。 提 供 所 有 对 象 的 依赖 意味 着 对 象 在 完全 初始 化 状态 
时 ， 通 常 要 返回 客户 端 (调用 ) 代码 。 这 个 缺点 会 使 得 对 象 变 得 不 适合 去 重新 配置 
或 重新 注入 。 

使 用 依赖 注入 的 时 候 要 特别 注意 一 些 类 。 当 要 选择 处 理 没 有 源 代码 时 的 第 三 方 类 库 
的 时 候 。 遗 留 的 类 可 能 没有 暴露 任何 setter 方法 ， 而 构造 方法 注入 则 是 唯一 可 用 的 
依赖 注入 方式 。 

4.4.1.3 解决 依赖 过 程 

容器 按 如 下 步骤 来 解决 bean 的 依赖 : 


1. ApplicationContext 和 描述 了 所 有 bean 的 配置 元 数据 一 起 被 创建 并 初始 化 。 配 
置 元 数据 可 以 通过 XML? Java 代码 或 注解 来 指定 。 


2. 对 于 每 一 个 bean 来 说 ， 它 的 依赖 被 表述 为 属性 ， 构 造 方法 参数 的 形式 ， 如 果 
你 使 用 了 静态 工厂 方法 来 代替 构造 方法 ， 那 么 还 会 是 静态 工厂 方法 参数 的 形 
式 。 当 bean 被 实际 创 建 时 ， 这 些 依赖 被 提供 给 bean。 


3. 每 个 属性 或 构造 方法 参数 就 是 一 个 要 被 设置 的 值 或 者 是 容器 中 其 它 bean 的 引 
用 。 


4. 每 个 属性 或 构造 方法 参数 值 会 被 转换 特定 格式 的 形式 ， 去 匹配 属性 或 构造 方法 
参数 的 类 型 。 上 默认 情况 下 ，Spring 可 以 转换 给 定 的 字符 串 格 式 的 值 到 内 建 的 类 
A > ye% int > long > String > boolean 等 。 


当 容 器 被 创建 时 ，Spring 容器 会 来 验证 每 个 bean 的 配置 ， 包 括 验 证 bean 的 引用 

属性 是 否 是 一 个 合法 的 bean。 然 而 ，bean 属性 本 身 直到 bean AERA E BKE 
才 被 设置 进去 。 当 容 器 被 创建 时 ，bean 的 范围 是 单 例 时 ， 会 被 设置 成 预 实例 (R 
认 情 况 ) 来 创建 。 范 围 在 4.5 F > “bean 的 范围 "部 分 来 解释 。 否 则 ，bean 就 会 当 

被 请 求 的 时 候 被 创建 。 一 个 bean 的 创建 潜在 地 会 引起 一 系列 bean 被 创建 ， 因 为 

bean 的 依赖 和 它 依赖 的 依赖 (等 等 ) 要 不 创建 和 定义 出 来 。 


循环 依赖 如 果 你 使 用 主要 的 构造 方法 注入 ， 就 可 能 会 引起 不 可 解决 的 循环 依赖 情 
形 。 上 比如 ， 类 人 需要 通过 构造 方法 注入 获得 类 B 的 实例 ， 而 类 BB 也 需要 通过 构造 
方法 注入 获得 类 A 的 实例 。 如 果 把 类 A PRB 进行 相互 注入 ，Spring 的 loc 容器 
会 在 运行 时 检 测 到 这 是 循环 引用 的 情况 ， 并 且 抛 出 
BeanCurrentlyInCreationException 异常 。 

一 个 可 行 的 方案 是 编辑 一 些 要 配置 的 类 的 源码 ， 通 过 setter 方法 而 不 是 构造 方法 进 
行 注 入 。 而 且 ， 避 免 构 造 方法 注入 并 仅仅 使 用 setter 方法 注入 。 换 名 话说 ， 尽 管 这 
不 是 推荐 做 法 ， 你 可 以 通过 setter 方法 注入 来 配置 循环 依赖 。 


不 像 典 型 的 用 例 (没有 循环 依赖 ) ， 在 beanA 和 beanB 之 间 的 循环 依赖 强制 一 个 
bean 被 注入 到 另 一 个 中 会 先 于 被 完全 初始 化 自己 (就 是 经 典 的 鸡 和 有 蛋 的 问题 ) 。 


通常 情况 下 你 可 以 信任 Spring 做 出 正确 的 事情 。 它 会 在 容器 加 载 时 来 检测 配置 问 
A> 比如 引用 了 一 个 不 存在 的 bean 和 循环 依赖 问题 。 当 bean 被 实际 创建 出 来 

后 ，Spring 设置 属性 和 解决 依赖 会 尽量 地 晚 些 。 这 就 意味 着 Spring 容器 已 经 加 载 
正确 了 但 晚 些 时 候 可 能 会 生 成 异常 ， 比 如 当 你 请 求 一 个 创建 时 发 生 问题 的 对 象 或 者 
是 它 的 依赖 发 送 问 题 。 例 如 ，bean 因为 丢失 或 非法 属性 而 抛 出 异常 。 这 种 潜在 的 
一 些 配置 问题 的 可 见 度 延迟 也 就 是 为 什么 ApplicationContext 的 实现 类 默认 情况 都 
是 预 实例 的 单 例 bean。 在 前 期 的 时 间 和 内 存 消耗 中 ， 在 bean AE HRA RAK 
这 些 bean > 4 ApplicationContext 被 创建 的 时 候 ， 你 会 发 现 这 些 配置 问题 ， 这 还 
不 晚 。 你 也 可 以 履 盖 这 个 默认 的 行为 ， 那 么 单 例 bean 就 会 延 迟 加 载 ， 而 不 是 预 实 
例 的 了 。 


如 果 没 有 循环 依赖 的 存在 ， 当 一 个 或 多 个 协作 的 bean 被 注入 到 一 个 独立 的 bean 
时 ， 每 个 协作 的 bean 就 会 在 被 注入 之 前 完全 被 配置 好 。 这 就 意味 着 如 果 bean A 
xt bean B Aik ñ > IRZ Spring 的 loC 容器 会 完全 配置 bean B 而 优先 于 调用 
bean 人 A 中 的 setter 方法 。 换 多 话说 ，bean 被 实例 化 了 【而 不 是 预 实例 的 单 例 
bean) ， 它 的 依赖 才 被 注入 ， 相 关 的 生命 周 期 方法 (比如 配置 初始 化 方法 
(4.6.1.1 节 ) 或 InitializingBea n 的 回调 方法 (4.6.1.1 节 ) ) T 被 调用 。 


4.4.1.4 依赖 注入 示例 


下 面 的 示例 使 用 了 基于 XML 的 配置 元 数据 来 进行 基于 setter 方法 的 依赖 注入 。 
Spring XML 配置 文件 的 一 小 部 分 来 指定 几 个 bean 的 定义 : 


<bean id="exampleBean" class="examples.ExampleBean"> 
<!-- (RA RA<ref/>4) TH Rew (TsetterA KzEA<ref/> --> 
<property name="beanOne"> 
<ref bean="anotherExampleBean"/> 
</property> 
<!-- 使 用 整洁 的 'ref' 属 性 来 进行 Setter 方 法 注入 - -> 
<property name="beanTwo" ref="yetAnotherBean"/> 
<property name="integerProperty" value="1"/> 
</bean> 
<bean id="anotherExampleBean" class="examples.AnotherBean"/> 
<bean id="yetAnotherBean" class="examples.YetAnotherBean"/> 
public class ExampleBean { 
private AnotherBean beanOne; private YetAnotherBean beanTwo; 
private int i; 
public void setBeanOne(AnotherBean beanOne) { 
this.beanOne = beanOne; 


public void setBeanTwo(YetAnotherBean beanTwo) { 
this.beanTwo = beanTwo; 


public void setIntegerProperty(int i) { 
this.i = i; 
} 


上 面 的 示例 中 ，setter 方法 被 声明 为 匹配 XML 文件 中 指定 的 属性 。 下 面 的 示例 使 用 
基于 构造 方法 的 依赖 注入 : 


<bean id="exampleBean" class="examples.ExampleBean"> 
<!-- 使 用 区 入 的 <ref/> 元 素 进 行 构造 方法 注入 --> 
<constructor -arg> 
<ref bean="anotherExampleBean"/> 
</constructor-arg> 
<!-- 使 用 整洁 的 "ref' 属 性 来 进行 构造 方法 注入 --> 
<constructor-arg ref="yetAnotherBean"/> 
<constructor-arg type="int" value="1"/> 
</bean> 
<bean id="anotherExampleBean" class="examples.AnotherBean"/> 
<bean id="yetAnotherBean" class="examples.YetAnotherBean"/> 
public class ExampleBean { 
private AnotherBean beanOne; private YetAnotherBean beanTwo; 
private int i; 
public ExampleBean(AnotherBean anotherBean, YetAnotherBean y 
etAnotherBean, int i) { 
this .beanOne 
this .beanTwo 
this.i = 1; 


anotherBean; 
yetAnotherBean; 


在 bean 中 指定 的 构造 方法 参数 会 被 用 于 ExampleBean 的 构造 方法 参数 。 MAF 
虑 一 下 这 个 示例 的 变化 情况 ， 要 代替 使 用 构造 方法 ，Spring 被 告知 调用 static 


工厂 方法 并 返回 一 个 对 象 的 实例 : 


<bean id="exampleBean" class="examples.ExampleBean" factory- 
method="createInstance"> 

<constructor-arg ref="anotherExampleBean"/> 

<constructor-arg ref="yetAnotherBean"/> 

<constructor-arg value="1"/> 
</bean> 
<bean id="anotherExampleBean" class="examples.AnotherBean"/> 
<bean id="yetAnotherBean" class="examples.YetAnotherBean"/> 
public class ExampleBean { 

// 私有 的 构造 方法 

private ExampleBean(...) { 


} 
// BAL Fk; 这 个 方法 的 参数 可 以 被 认为 是 要 返回 bean 的 依赖 ， 
// 而 不 管 那些 参数 是 如 何 被 使 用 的 。 
public static ExampleBean createInstance (AnotherBean anothe 
rBean, 
YetAnotherBean yetAnotherBean, int i) { 
ExampleBean eb = new ExampleBean (...); 
// 其 它 的 操作 . . ， 
return eb; 


static 工厂 方法 的 参数 通过 <constructor-arg/> 元 素来 提供 ， 这 和 构造 方法 已 经 
被 实际 调用 是 完全 一 致 的 。 由 工厂 方法 返回 的 类 的 类 型 不 需要 和 包含 static 工厂 方 
法 类 的 类 型 相同 ， 尽 管 在 本 例 中 是 相同 的 。 实 例 ( 非 静态 ) 工厂 方法 可 以 被 用 于 本 
质 上 相同 的 方式 (除了 factory-bean 属性 的 使 用 ， 来 代替 class BE) ， 所 以 这 里 
不 讨论 它们 的 细节 。 


4.4.2 深入 依赖 和 配置 


正如 之 前 章节 中 所 提 到 的 ， 你 可 以 定义 bean 的 属性 和 构造 方法 参数 作为 其 它 被 管 
理 bean (协作 者 ) 的 引用 ， 或 者 作为 内 联 值 的 定义 。 出 于 这 个 目的 ，Spring 的 基 
于 XML 的 配 置 元 数据 支持 使 用 <property/> 和 <constructor-arg/> 元 素 的 
子 元 素 类 型 。 


4.4.2.1 直接 值 (原生 类 型 ，String， 等 ) 


LK value 属性 指定 了 属性 或 构造 方法 参数 ， 这 是 人 们 可 以 阅读 的 字符 事 的 表 
达 。 正 如 之 前 提 到 过 的 (6.4.2 节 ) > JavaBean 的 PropertyEditor 可 以 用 来 转换 
这 些 字符 串 值 从 String 到 属性 或 参数 的 站 实 类 型 。 


<bean id="myDataSource" class="org.apache.commons.dbcp.BasicData 
Source" destroy-method="close"> 

<!-- setDriverClassName(String) > AWA 42 R --> 

<property name="driverClassName" value="com.mysql.jdbc.Drive 
r"/> 

<property name="url" value="jdbc:mysql://localhost :3306/mydb 
WS 

<property name="username" value="root"/> 

<property name="password" value="masterkaoli"/> 
</bean> 


对 于 更 简洁 的 XML 配置 ， 下 面 的 示例 使 用 了 p- 命 名 空间 (44.267) 。 


<beans xmlns="http://ww.springframework.org/schema/beans" 
xmins:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmins:p="http://www. springframework.org/schema/p" 
XSi:schemaLocation="http://www.springframework.org/schema/be 
ans 
http://www. springframework.org/schema/beans/spring -beans-3. 
0.xs d"> 
<bean id="myDataSource" class="org.apache.commons.dbcp.Basic 
DataSource" destroy-method="close" p:driverClassName="com.mysql. 
jdbc.Driver" p:url="jdbc:mysql://localhost:3306/mydb" p:username 
="root" p:password="masterkaoli"/> 
</beans> 


上 面 的 XML 非常 简洁 ; 然而 ， 错 误 之 处 会 在 运行 时 被 发 现 而 不 是 设计 的 时 候 ， 除 
非 在 你 创建 bean 的 时 候 ， 使 用 如 IntelliJ IDEA 或 SpringSource Tool 

Suite (STS > SpringSource 组 织 开发 的 工具 套件 ) 这 样 的 IDE 来 支持 自动 地 属性 
补 全 。 这 样 的 IDE 帮助 是 强烈 建议 使 用 的 。 


你 也 可 以 这 样 来 配置 java.util.Properties 实例 : 
<bean id="mappings" class="org.springframework.beans.factory.con 


fig.PropertyPlac 
eholderConfigurer"> 


<!-- #Ajava.util.PropertiesX# --> 
<property name="properties"> 
<value> 


jdbc.driver.className=com.mysql.jdbc.Driver jdbc.url 
=jdbc:mysql://localhost :3306/mydb 
</value> 
</property> 
</bean> 


Spring 容器 会 使 用 JavaBean 的 PropertyEditor 机 制 来 转换 <value/> 元 素 中 的 
文本 到 java.util.Properties 实例 。 这 是 一 个 很 好 的 捷径 ， 也 是 Spring 团队 少 有 喜 
RAS RBA <value/> 元 素 而 不 是 value 属性 方式 的 地 方 之 一 。 


idref 元 素 


idref 元 素 是 一 种 简单 防 错 的 形式 来 传递 容器 中 另外 一 个 bean 的 id 〈 字 符 串 值 而 不 
是 引用 ) 到 <constructor-arg/> 或 <property/> 元 素 中 。 


<bean id="theTargetBean" class="..."/> 
<bean id="theClientBean" class="..."> 
<property name="targetName"> 
<idref bean="theTargetBean" /> 
</property> 
</bean> 


上 面 定 义 bean 的 代码 片段 是 和 下 面 的 片段 完全 等 价 (在 运行 时 ) 


<bean id="theTargetBean" class="..." /> 
<bean id="client" class="..."> 

<property name="targetName" value="theTargetBean" /> 
</bean> 


第 一 种 形式 比 第 二 种 形式 可 取 ， 因 为 使 用 idref 标签 允许 容器 在 部 署 时 来 验证 被 引 
用 的 ， 命 名 的 bean 是 否 丨 的 存在 。 第 二 种 形式 下 ， 没 有 对 传递 给 client bean 的 
targetName 属性 执行 验证 。 错 误 仅 仅 是 在 Client bean 被 丨 正 实例 化 的 时 候 才 会 被 
发 现 (和 很 多 可 能 致命 的 结果 ) 。 如 果 client bean 是 prototype (4.5 节 ) 类 型 的 
bean， 这 个 错误 和 结果 异常 可 能 仅仅 在 容器 被 部 署 很 长 一 段 时 间 后 才 会 被 发 现 。 


此 外 ， 如 果 被 引用 的 bean 在 同一 个 XML 单元 中 ，bean 的 名 称 就 是 bean 的 id > 
那么 你 还 可 以 使 用 local 属性 ， 这 允许 XML 解析 器 本 身 在 XML 文档 解析 的 时 候 ， 
及 早 地 来 验证 bean 的 id。 


<property name="targetName"> 
<!-- id 为 'theTargetBean' 的 bean 必 须 存在 ;否则 就 会 抛 出 异常 --> 
<idref local="theTargetBean"/> 

</property> 


<idref/> 元 素 带 来 的 一 个 相同 之 处 (最少 是 Spring2.0 版 本 以 前 的 
) 是 值 在 ProxyFactoryBean 定义 的 AOP 拦截 器 的 配置 中 。 当 你 指定 拦截 器 名 称 
来 防止 拼 错 拦截 器 的 id 时 ， 可 以 使 用 <idref/> 元 素 。 


4.4.2.2 引用 其 它 bean (协作 者 ) 


ref 元 素 是 <constructor-arg/> 或 <property/> 定义 元 素 中 最 后 的 一 个 。 在 这 
里 你 可 以 为 bean 设置 指定 属性 的 值 ， 来 引用 被 容器 管理 的 另外 一 个 bean (协作 
者 ) 。 被 引用 的 bean 就 是 要 设置 属性 的 这 个 bean 的 一 个 依赖 ， 并 且 是 初始 化 的 
作为 属性 设置 之 前 的 点 播 。 (如 果 协 作者 是 一 个 单 例 的 bean， 它 可 能 已 经 被 容器 
初始 化 过 了 。) 所 有 引用 最 终 都 会 被 引用 到 一 个 对 象 中 。 范 围 和 验证 基于 通过 
bean，local 或 parent 属性 指定 id/name 的 其 它 对 象 。 


通过 <ref/> 标签 的 bean 属性 来 指定 目标 bean 是 最 常用 的 方式 ， 并 允许 创建 引 
用 到 相 同 容器 或 父 容器 的 任意 bean 中 ， 而 不 管 它们 是 不 是 在 同一 个 XML 文件 

+ ° bean 属 ， 性 的 信 Tå &47 Hix bean 的 id 属性 相同 ， 或 者 是 目标 bean 的 name 
属性 值 之 一 。 


<ref bean="someBean"/> 


通过 local 属性 来 指定 目标 bean 是 利用 了 XML 解析 器 的 能 力 ， 来 验证 XML 相同 
文件 内 的 id 引用 。local 属性 的 值 必须 和 目标 bean 的 id 属性 一 致 。 如 果 没 有 在 相 
同 的 文件 内 发 现 匹配 的 元 素 ， 那 么 XML 解析 器 会 报告 问题 。 因 此 ， 如 果 目 标 bean 
在 同一 个 XML 文件 中 的 话 ， 使 用 local 这 种 形式 是 最 佳 选择 (为 了 更 早 地 知道 错 


R) 。 
<ref local="someBean"/> 


通过 parent 属性 来 指定 目标 bean 会 为 bean 创建 引用 ， 它 是 在 当前 容器 的 父 容 
器 中 的 。parent 属性 的 值 可 能 和 目标 bean 49 id 属 ， 性 相 > 或 者 是 目 标 bean 的 
name 属性 值 之 一 ， 而 且 目 标 bean 必须 在 当前 容器 的 器 中 。 当 有 一 个 容器 继 
承 关系 ， 可 以 使 用 这 个 bean 的 引用 ， 或 在 你 起 使 用 和 全 Bean 有 相同 名 称 的 代理 
包装 一 个 父 容 器 中 已 有 bean 时 。 


ang 


aie > 
<bean id="accountService" class="com.foo.SimpleAccountService"> 
<1-- 在 这 里 插入 所 需要 的 依赖 --> 
</bean> 
<!-- AF (后 继 ) 上 下 文中 --> 
<bean id="accountService" <-- bean 名 称 和 父 bean 相 同 --> 
class="org.springframework.aop.framework.ProxyFactoryBean"> 
<property name="target"> 
<ref parent="accountService"/> 
<!-- 注意 我 们 如 何 引 用 父 bean --> 


</property> 
<1-- 在 这 里 插入 其 它 配置 和 所 需 的 依赖 - -> 
</bean> 


4.4.2.3 内 部 bean 


在 <property/> 或 <constructor-arg/> 元 素 内 部 的 <bean/> 元 素 的 定义 被 称 
为 内 部 bean。 


<bean id="outer" class="..."> 
<!-- 为 了 替代 为 目标 bean 使 用 引用 ， 简 单 内 联 定义 目标 bean --> 
<property name="target"> 
<bean class="com.example.Person"> <!-- 这 就 是 内 部 bean --> 
<property name="name" value="Fiona Apple"/> 
<property name="age" value="25"/> 
</bean> 
</property> 
</bean> 


这 


内 部 bean 的 定义 不 需要 定义 id A name ; 容器 忽略 这 些 值 。 也 会 忽略 scope 标 
识 。 内 部 bean 通常 是 匿名 的 ， 而 且 范 围 通常 是 prototype (4.5.2 节 ) 的 。 注 入 内 
部 bean 到 协作 bean 是 不 可 能 的 ， 只 能 到 包围 它 的 bean 中 。 


4.4.2.4 集合 


在 <list/> ， <set/> ， <map/> 和 <props/> 元 素 中 ， 你 可 以 分 别 设置 
Java 的 Collection 类 型 List，Set，Map 和 Properties 的 属性 和 参数 。 


<bean id="moreComplexObject" class="example.ComplexObject"> 


<!-- results in a setAdminEmails(java.util.Properties) call 
m> 
<property name="adminEmails"> 
<props> 
<prop 
key="administrator">administrator@example.org</prop> 
<prop key="Support">support@example.org</prop> 
<prop key="development">development@example.org</pro 
p> 
</props> 
</property> 
<!-- results in a setSomeList(java.util.List) call --> 
<property name="SomeList"> 
<list> 
<value>a list element followed by a reference</value 
> 
<ref bean="myDataSource" /> 
</list> 
</property> 
<!-- results in a setSomeMap(java.util.Map) call --> 
<property name="SomeMap"> 
<map> 
<entry key="an entry" value="just some string"/> 
<entry key ="a ref" value-ref="myDataSource"/> 
</map> 
</property> 
<!-- results in a setSomeSet(java.util.Set) call --> 
<property name="sSomeSet"> 
<set> 
<value>just some string</value> 
<ref bean="myDataSource" /> 
</set> 
</property> 
</bean> 


Map 类 型 的 key 或 value 的 值 ， 或 set 的 值 ， 也 可 以 是 下 列 元 素 之 一 : 


bean 
ref 
idref 
list 
set 
map 
props 
value 
null 


集合 合并 


> 


在 Spring 2.0 中 ， 容 器 支持 集合 的 合并 。 应 用 开发 人 员 可 以 定义 父 样 式 
的 <list/> > <map/> ， <set/> 或 <props/> 元 素 ， 子 样式 

的 <list/> ， <map/> ， <set/> 或 <props/> 元 素 继 承 或 重 写 来 自 父 集合 的 
值 。 也 就 是 说 ， 子 集合 的 值 是 合并 元 素 父 与 子 集合 中 的 元 素 ， 和 子 集合 元 素 履 盖 父 
集合 中 指定 值 的 结果 。 


本 节 关 于 导论 父子 bean 合并 的 机 制 。 如 果 读 者 不 熟悉 父 和 子 bean 的 定义 ， 可 能 
要 先 去 阅读 一 下 相关 章节 (4.7 节 ) © 


下 面 的 示例 说 明了 集合 合并 : 


<beans> 
<bean id="parent" abstract="true" class="example.ComplexObje 
CUTS 
<property name="adminEmails"> 
<props> 
<prop 
key="administrator">administrator@example.com</p 
rop> 
<prop key="Support">support@example.com</prop> 
</props> 
</property> 
</bean> 
<bean id="child" parent="parent"> 
<property name="adminEmails"> 
<1-- 合并 在 * 子 * 集 合 定义 中 来 指定 definition --> 
<props merge="true"> 
<prop key="sales">sales@example.com</prop> 
<prop key="Support">support@example.co.uk</prop> 
</props> 
</property> 
</bean> 
<beans> 


注意 在 child bean 中 的 adminEmails 属性 下 的 <props/> 元 素 中 的 merge=true 
属性 的 使 用 。 当 child bean 被 容器 处 理 并 实例 化 时 ， 结 果实 例 中 有 一 个 
adminEmails Properties 的 集合 ， 包 含 了 合并 子 bean 的 adminEmails 集合 和 
父 bean 的 adminEmails 集合 。 


administrator=administrator@example.com 
sales=sales@example.com 
support=support@example.co.uk 


F bean 的 Properties 集合 的 值 设 置 继承 了 从 父 <props/> 元 素 而 来 的 所 有 属性 ， 
F bean 中 support #9 4% & T X bean 中 的 值 。 


这 种 合并 行为 的 应 用 和 <list/> > <map/> 和 <set/> 集合 类 型 很 相似 。 
在 <list/> 元 素 特 定 的 情形 下 ， 和 List 集合 类 型 相关 的 语义 ， 也 就 是 说 ， 
ordered 集合 值 的 概念 ， 是 要 维 护 的 ; 父 值 优 先 于 所 有 子 list 的 值 。 在 Map，Set 


和 Properties 集合 类 型 的 情况 下 ， 没 有 顺序 的 存在 。 因 此 对 于 容器 内 部 使 用 的 ， 和 
Map，Set 和 Properties 实现 类 型 相关 的 集合 类 型 没有 排序 语义 的 作用 。 


集合 合并 的 限制 


不 能 合并 不 同类 型 的 集合 (比如 Map fe List) ， 如 果 你 要 尝试 这 么 去 做 ， 那 么 就 会 
Ja 出 Exception。merge 属性 必须 在 低级 的 ， 继 承 的 ， 子 bean 中 来 指定 ; 在 父 集 
合 中 指定 merge 属性 是 宛 余 的 ， 也 不 会 看 到 想 要 的 合并 结果 。 合 并 特性 仅 在 
Spring 2.0 和 更 高 版 本 中 可 用 。 


强 类 型 集合 (Java 5 以 上 版 本 ) 


在 Java 5 或 更 高 版 本 中 ， 你 可 以 使 用 强 类 型 集合 (使 用 泛 型 ) 。 也 就 是 说 ， 可 以 
声明 一 个 Collection 类 型 ， 它 可 以 仅仅 包含 String TH (作为 示例 ) 。 如 果 你 使 用 
Spring 来 对 强 类 型 的 Collection 依赖 注入 到 bean 中 ， 你 可 以 利用 Spring 的 类 型 转 
换 来 支持 这 样 强 类 型 Collection 实例 的 元 素 ， 在 被 加 到 Collection 之 前 ， 可 以 转换 
成 合适 的 类 型 。 


public class Foo { 
private Map<String, Float> accounts; 
public void setAccounts(Map<String, Float> accounts) { 
this.accounts = accounts; 


} 
} 
<beans> 
<bean id="foo" class="x.y.Foo"> 
<property name="accounts"> 
<map> 
<entry key="one" value="9.99"/> 
<entry key="two" value="2.75"/> 
<entry key="six" value="3.99"/> 
</map> 
</property> 
</bean> 
</beans> 


当 foo bean 的 accounts 属性 准备 好 注入 时 ， 关 于 强 类 型 元 素 

Map<String, Float> 类 型 的 泛 型 信息 就 通过 反射 机 制 准备 好 了 。 因 此 Spring 的 
类 型 转换 工具 识别 到 各 种 元 素 的 值 作 为 Float 类 型 ， 字 符 串 值 9.99，2.75 和 3.99 
被 转换 成 实际 的 Float 类 型 。 


4.4.2.5 null 和 空 字 符 串 


Spring 将 属性 的 空 参 数 当 作 空 String。 下 面 基 于 XML 的 配置 元 数据 片段 设置 了 电 
Fup 件 属 性 为 空 String 值 (") 。 


<bean class="ExampleBean"> 
<property name="email" value=""/> 
</bean> 


上 面 的 例子 和 下 面 的 Java 代码 是 一 样 的 : exampleBean.setEmail("")。 <null/> 
元 素 控制 null 值 。 比 如 : 


<bean class="ExampleBean"> 
<property name="email"><null/></property> 
</bean> 


上 面 的 配置 和 下 面 的 Java 代码 一 致 : exampleBean.setEmail(null) ° 


4.4.2.6 使 用 p- 命 名 空间 的 XML 快捷 方式 


p- 命 名 空间 可 以 使 你 使 用 bean 的 元 素 属 性 ， 而 不 是 内 眶 的 <property/> 元 素 ， 
来 描述 属 性 的 值 和 /或 协作 的 bean。 


Spring 2.0 和 后 续 版 本 支持 使 用 命名 空间 (附录 C) 的 可 扩展 的 配置 格式 ， 这 是 基 
于 XML 的 Schema 定义 的 。 本 章 中 讨论 的 bean 的 配置 格式 是 定义 在 XML 的 
Schema 下 的 。 然 而 ，p- 命 名 空间 则 不 是 定义 在 XSD 文件 下 的 ， 仅 仅 存在 于 
Spring 的 核心 中 。 下面 的 示例 展示 了 两 个 XML 片段 ， 解 析 得 到 相同 的 结果 : 第 一 
个 使 用 了 标准 的 XML 格式 ， 第 二 个 使 用 了 p- 命 名 空间 。 


<beans xmlns="http://www.springframework.org/schema/beans" 
xmins:xsi="http://www.w3.org/2001/XMLSchema -instance" 
xmins:p="http://www. springframework.org/schema/p" 
xSi:schemaLocation="http://www.springframework.org/schema/be 
ans 
http://www. springframework.org/schema/beans/spring -beans-3. 
0.xsd"> 
<bean name="Classic" class="com.example.ExampleBean"> 
<property name="email" value=["foo@bar .co] (mailto: foo@ba 
r.com)m"/> 
</bean> 
<bean name="p-namespace" class="com.example.ExampleBean" p:e 
mail=["foo@bar.co] (mailto: foo@bar .com)m"/> 
</beans> 


示例 展示 了 p- 命 名 空间 下 的 属性 ， 在 bean 的 定义 中 称 为 email。 这 就 告诉 Spring 
来 包 含 属性 声明 。 正 如 前 面 提 到 的 ，p- 命 名 空间 没有 schema 定义 ， 所 以 你 可 以 设 
置 属性 的 名 称 和 bean 中 属性 的 名 称 一 样 。 


下 面 的 示例 包含 了 两 个 bean 的 定义 ， 两 者 都 有 对 其 它 bean 的 引用 : 


<beans xmlns="http://ww.springframework.org/schema/beans" 
xmins:xsi="http://www.w3.org/2001/XMLSchema -instance" 
xmins:p="http://www. springframework.org/schema/p" 
xsi:schemaLocation"http://www.springframework.org/schema/bea 
ns 
http: //www.springframework.org/schema/beans/spring -beans-3. 
0.xsd"> 
<bean name="john-classic" class="com.example.Person"> 
<property name="name" value="John Doe"/> 
<property name="Spouse" ref="jane"/> 
</bean> 
<bean name="john-modern" class="com.example.Person" p:name=" 
John Doe" p:spouse-ref="jane"/> 
<bean name="jane" class="com.example.Person"> 
<property name="name" value="Jane Doe"/> 
</bean> 
</beans> 


正如 你 所 看 到 的 一 样 ， 这 个 例子 包含 着 不 仅仅 使 用 了 p- 命 名 空间 的 属性 值 ， 也 使 用 

了 特殊 格式 来 声明 属性 的 引用 。 在 第 一 个 bean 中 使 用 

了 <property name="spouse" ref="jane"/> 来 创建 john bean 对 jane bean 的 

引用 关系 ， > 第 二 个 bean 中 ， 使 用 了 p:spouse-ref="jane" 作 为 属性 来 做 相同 的 事 

ud o AM] P > spouse 是 属性 名 ， 而 -ref 部 分 表明 了 这 不 是 一 个 直接 值 而 是 一 个 对 其 
€ bean 的 引用 。 


ny 
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-命名 空间 没有 标准 XML 格式 那么 灵活 。 上 比如， 声明 属性 引用 的 格式 和 以 Ref 
属性 相 冲突 ， 而 标准 的 XML 格式 则 不 会 。 我 们 建议 谨 懂 选择 所 用 的 方 
法 并 和 开发 团 队 成 员 充分 地 交流 ， 避 免 产 生 同 时 使 用 这 三 种 方法 的 XML X 
档 。 


4.4.2.7 使 用 c- 命 名 空间 的 XML 快捷 方式 


和 4.4.2.6 节 ，“ 使 用 p- 命 名 空间 的 XML 快捷 方式 "相似 ，C- 命 名 空间 是 在 Spring 
Ce 
arg 元 素 。 


我 们 来 看 4.4.1.1 节 ，“ 基 于 构造 方法 的 依赖 注入 "中 的 示例 ， 现 在 使 用 c 命名 空间 : 


<beans xmlns="http://www.springframework.org/schema/beans" xmins 
>XS1="http://www.w3.org/2001/XMLSchema -instance" xmlns:p="http: 
//www.Springframework.org/schema/c" xsi:schemaLocation="http://w 
ww.springframework.org/schema/beans http://www. springframework.o 
rg/schema/beans/spring-beans.xsd"> 
<bean id="bar" class="x.y.Bar"/> 
<bean id="baz" class="x.y.Baz"/> 
<-- "传统 的 ! 声 明 方 式 --> 
<bean id="foo" class="x.y.Foo"> 
<constructor-arg ref="bar"/> 
<constructor-arg ref="baz"/> 
<constructor-arg value=["foo@bar.co](mailto: foo@bar .com) 
m"/> 
</bean> 
<-- !'C- 命 名 空间 ' 声 明 方 式 --> 
<bean et class="x.y.Foo" c:bar-ref="bar" c:baz-ref="ba 
z" c:email=["foo@bar.co](mailto:foo@bar.com)m"> 
</beans> 


命名 空间 使 用 了 和 p: (以 -ref 结尾 的 bean 引用 ) 相同 的 转换 机 制 通过 它们 的 名 
和 # REM ED RAM 这 样 一 来 ， 即便 没有 在 XSD schema (但 是 存在 于 
Spring 核心 的 内 部 ) 中 定义 ， 它 还 是 需要 声明 出 来 。 


在 极 少 数 的 情况 下 ， 构 造 方法 参数 名 称 是 不 可 用 的 (通常 如 果 字 节 码 在 编译 时 没有 
调试 信息 ) ， 我 们 可 以 使 用 参数 索引 : 


<-- 'C- 命 名 空间 ' 索 引 声 明 --> 
<bean id="foo" class="x.y.Foo" c:_0-ref="bar" c:_1-ref="baz"> 


AA XML 的 语法 ， 索 引 符 号 需要 在 其 头 部 使 用 作为 XML 属性 名 称 ， 因 为 
XML 中 属性 是 不 能 以 数字 开头 的 (尽管 一 些 IDE 允许 这 样 做 ) 。 


在 实际 运用 中 ， 构 造 方法 解析 机 制 (4.4.1.1 节 ) 在 匹配 参数 时 是 非常 有 效率 的 ， 所 
以 除 非 瘟 有 需要 ， 我 们 建议 在 配置 中 使 用 名 称 符号 。 


4.4.2.8 复合 属性 名 称 


在 设置 bean 的 属性 时 ， 只 要 路 径 中 的 所 有 组 件 ， 除 了 最 后 一 个 属性 名 称 是 非 null 
的 ， 可 以 使 用 复合 或 者 上 获 套 的 属性 名 称 。 参 考 下 面 的 bean 定义 。 


<bean id="foo" class="foo.Bar"> 


<property name="fred.bob.sammy" value="123" /> 
</bean> 


foo bean 有 一 个 fred 属性 ， 它 还 有 一 个 bob 属性 ， 而 它 仍 有 一 个 sammy 属性 ， 
而 最 终 的 sammy 属性 被 设置 成 数值 123。 为 了 让 这 样 的 配置 可 用 ，foo 的 属性 
fred > fred 的 属性 bob 在 bean 被 构造 好 后 必须 不 能 为 null， 否 则 会 抛 出 
NullPointerException 异常 。 


4.4.3 使 用 depends-on 


如 果 一 个 bean 是 另外 一 个 bean 的 依赖 ， 通 常 表 明了 它 会 被 设置 成 另外 一 个 的 属 

性 。 典 型 的 情况 是 在 基于 XML 的 配置 元 数据 中 使 用 <ref/> (4.4.2.2 节 ) 元 素 

来 完成 。 然 而 ， 有 时 在 两 个 bean 之 间 的 依赖 并 不 是 直接 的 ; 比如 ， 类 中 的 静态 初 
始 化 器 需要 触发 ， 就 像 数据 库 驱 动 程序 的 注册 。depends-on 属性 可 以 明确 地 强制 
一 个 或 多 个 bean 在 使 用 这 个 元 素 的 bean 被 初始 化 之 前 被 初始 化 。 下 面 的 示例 使 

用 了 depends-on 属性 来 表示 一 个 独立 bean 的 依赖 : 


<bean id="beanOne" class="ExampleBean" depends-on="manager"/> 
<bean id="manager" class="ManagerBean" /> 


为 了 表示 对 多 个 bean 的 依赖 ， 提 供 一 个 bean 名 称 的 列表 作为 depends-on 属性 的 
值 即 可 ， 要 用 去 号 ， 空 白 或 分 号 分 隔 开 ， 它 们 都 是 有 效 的 分 隔 符 : 


<bean id="beanOne" class="ExampleBean" depends-on="manager,accou 
ntDao"> 
<property name="manager" ref="manager" /> 
</bean> 
<bean id="manager" class="ManagerBean" /> 
<bean id="accountDao" class="x.y.jdbc.JdbcAccountDao" /> 
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在 bean 定义 中 的 depends-on 属性 可 以 指定 初始 化 时 的 依赖 ， 也 可 以 是 仅仅 
是 单 例 (4.5.1 节 ) bean， 对 应 销毁 时 的 依赖 。 和 给 定 bean 定义 了 depends- 
on 关系 的 依赖 bean 首先 被 销毁 ， 先 于 给 定 的 bean 本 身 。 因 此 depends-on 
也 能 控制 关闭 顺序 。 


4.4.4 3£38 774614 bean 


默认 情况 下 ，ApplicationContext 的 实现 类 积极 地 创建 并 配置 所 有 单 例 的 bean 

(4.5.1 节 ) ， 作 为 初始 化 过 程 的 一 部 分 。 通 常 来 说 ， 这 种 预 实例 化 是 非常 可 取 
的 ， 因 为 在 配 置 或 周边 环境 中 的 错误 可 以 直接 被 发 现 ， 而 不 是 几 小 时 或 几 天 后 去 发 
现 。 当 这 种 行为 不 可 用 时 ， 你 可 以 阻止 单 例 bean 的 预 实例 化 ， 在 bean 定义 中 使 
用 延迟 初始 化 来 标记 一 下 就 可 以 了。 延迟 初始 化 bean 告诉 loC 容器 在 该 bean 第 
一 次 被 请 求 时 再 来 实例 化 ， 而 不 是 在 启动 时 实例 化 。 


在 XML 中 ， 这 个 行为 可 以 通过 <bean/> AKKI lazy-init 属性 来 控制 ; 比如 : 


<bean id="lazy" class="com.foo.ExpensiveToCreateBean" lazy-init= 
"true"/> 
<bean name="not.lazy" class="com.foo.AnotherBean"/> 


当前 者 配置 被 ApplicationContext 处 理 时 ， 命 名 为 lazy 的 bean 并 不 会 在 


ApplicationContext 局 动 时 被 预 实例 化 ， 而 notlazy bean 会 被 先 预 实例 化 。 my Bl 
RAE bean 是 一 个 单 例 bean 的 依赖 时 ， 且 这 个 单 例 bean 不 是 延迟 初始 化 的 ， 
那么 ApplicationContext 也 会 在 启动 时 来 创建 延迟 初始 化 的 bean， 因 为 它 必 须 满足 
单 例 bean 的 依赖 。 延 迟 初始 化 的 bean 被 注入 到 单 例 bean 中 的 时 候 它 就 不 是 延 
迟 初始 化 的 了 。 


你 也 可 以 在 容器 级 别 来 控制 延 迟 初 始 化 ， 在 <beans/> 元 素 上 使 用 default-lazy- 
init 属性 ; 比如 : 


<beans default-lazy-init="true"> 
<!-- 那么 就 没有 bean 是 预 实例 化 的 了 . ., ，--> 
</beans> 


44.5 自动 装配 协作 者 


Spring 容器 可 以 自动 装配 协作 bean 之 间 的 关系 。 你 可 以 允许 Spring 自动 为 你 的 
bean 来 解析 协作 者 (其它 bean) ， 通 过 检查 ApplicationContext 的 内 容 即 可 。 自 
动 装 配 有 下 列 优势 : 


自动 装配 可 以 显著 减少 指定 属性 或 构造 方法 参数 的 需要 。 (如 bean 模板 的 机 制 ， 
这 将 在 本 章 的 AT 节 来 讨论 ， 在 这 方面 是 有 价值 的 。) 


自动 装配 可 以 更 新 配置 对 象 的 演变 。 比 如 ， 如 果 你 需要 给 一 个 类 添加 依赖 ， 那 个 依 
赖 可 以 自动 被 填 入 而 不 需要 修改 配置 。 因 此 ， 自 动 装配 在 开发 期 间 是 非常 有 用 的 ， 
当代 码 库 变 得 更 稳定 时 切换 到 明确 的 装配 也 没有 否定 的 选择 。 


当 使 用 基于 XML 的 配置 元 数据 (4.4.1 F) 时 ， 你 可 以 为 bean 的 定义 指定 自动 装 
配 模 式 ， 在 <bean/> 元 素 上 设置 autowire 属性 即 可 。 自 动 装配 功能 有 五 种 模 

式 。 你 可 以 为 每 个 bean 来 指定 自动 装配 ， 因 此 可 以 选择 为 哪 一 个 来 指定 自动 装 
Ae o 


表 4.2 自动 装配 模式 


模式 解释 


(默认 情况 ) 没有 自动 装配 。Bean 的 引用 必须 通过 ref 元 素来 定 
义 。 对 于 大 型 的 部 署 ， 修 改 默 认 设 置 是 不 推荐 的 ， 因 为 明确 地 指 
定 协作 者 会 给 予 更 多 的 控制 和 清晰 。 某 种 程度 上 来 说 ， 它 匀 勒 出 
了 系统 的 结构 。 


通过 属性 名 称 来 自动 装配 。Spring 以 相同 名 称 来 查找 需要 被 自动 

装配 的 bean。 比 如 ， 如 果 bean 被 设置 成 由 名 称 来 自动 装配 ， 并 
byName 含有 一 个 master 属性 (也 就 说 ， 有 setMaster(..) 方 法 ) > 

Spring 会 查找 名 为 master 的 bean 定义 ， 并 且 用 它 来 设置 属 

性 o 


如 果 bean 的 属性 类 型 在 容器 中 存在 的 话 ， 就 允许 属性 被 自动 装 
配 。 如 果 存 在 多 于 一 个 ， 就 会 抛 出 致命 的 异常 ， 这 就 说 明了 对 那 
个 bean 不 能 使 用 byType 进行 自动 装配 。 如 果 没 有 匹配 的 bean 
存在 ， 就 不 会 有 任何 效果 ; 属性 不 会 被 设置 。 


和 byType 类 似 ， 但 是 是 应 用 于 构造 方法 参数 的 。 如 果 在 容器 中 
constructor ”没有 确定 的 构造 方法 参数 类 型 的 bean 的 存在 ， 就 会 发 生 致命 的 
错误 。 


no 


byType 


使 用 byType & constructor 自动 装配 模式 ， 你 可 以 装配 数组 和 集合 类 型 。 这 种 情况 
下 所 有 在 容器 内 匹配 期 望 类 型 的 自动 装配 候选 者 会 被 用 来 满足 依赖 。 如 果 期 望 的 键 
类 型 是 String， 你 可 以 自动 装配 强 类 型 的 Map。 自 动 装配 的 Map 值 会 包括 匹配 期 望 
类 型 的 实例 ， 而 且 Map 的 键 会 包含 对 应 bean 的 名 称 。 


你 可 以 联合 自动 装配 行为 和 依赖 检查 ， 这 会 在 自动 装配 完成 之 后 执行 。 


4.4.5.1 自动 装配 的 限制 和 缺点 


当 在 项 目 中 一 直 使 用 时 ， 自 动 装 配 是 非常 不 错 的 。 如 果 自 动 装配 通常 是 不 使 用 的 ， 
它 就 可 能 会 迷惑 开发 人 员 来 使 用 它 去 装配 仅仅 一 两 个 bean ° 


考虑 一 下 自动 装配 的 限制 和 缺点 : 


e 在 property 和 constructor-arg 中 设置 的 明确 依赖 通常 覆盖 自动 装配 。 不 能 
动 装配 所 谓 的 简单 属性 ， 比 如 原生 类 型 ，String 和 Class (还 有 这 样 简 单 属性 
的 数字 ) 。 这 是 由 于 设计 的 限制 。 


o 自动 装配 没有 明确 装配 那么 精确 ， 尽 管 ， 在 上 面 的 表格 中 已 经 说 明了 ，Spring 
很 小 心地 避免 在 有 歧义 的 情况 下 去 猜测 ， 但 也 可 能 会 有 意 想不到 的 结果 ， 在 
Spring 管理 的 对 象 中 间 的 关系 可 能 就 不 会 再 清晰 地 说 明了 。 

o 装配 信息 可 能 对 从 Spring 容器 中 来 生成 文档 的 工具 来 说 不 可 用 。 

e 在 容器 中 的 多 个 bean 定义 可 能 通过 setter 方法 或 构造 方法 参数 匹配 指定 的 类 
型 进行 自 动 装配 。 对 于 数组 ， 集 合 或 Map， 这 不 一 定 是 一 个 问题 。 而 对 期 望 
简单 值 的 依赖 ， 这 种 歧义 不 能 随意 解决 。 如 果 没 有 唯一 的 bean 可 用 ， 就 会 抛 
出 异常 。 在 后 面 一 种 情况 中 ， 你 有 几 种 选择 : 


© 放弃 自动 装配 而 使 用 明确 的 装配 。 


e 避免 设置 它 的 autowire-candidate 属性 为 false 来 自动 装配 bean， 这 会 在 下 一 
节 中 来 解释 。 


e 设置 <bean/> 元 素 的 primary 属性 为 true 来 指定 单独 的 bean 作为 主要 的 候 
选 者 。 


e。 如 果 你 使 用 Java 5 或 更 高 版 本 ， 使 用 基于 注解 的 配置 实现 更 细 粒 度 的 控制 ， 
这 会 在 4.9 节 ，“ 基 于 注解 的 容器 配置 "中 来 解释 。 


4.4.5.2 从 自动 装配 中 排除 bean 


在 每 个 bean 的 基础 上 ， 你 可 以 从 自动 装配 中 来 排除 bean。 在 Spring 的 XML 格式 
配置 中 ， 设 置 <bean/> 元 素 的 autowire-candidate 属性 为 false: 容器 会 把 指定 
的 bean 对 自动 装配 不 可 用 (包含 注解 风格 的 配置 ， 比 如 @Autowired (4.9.2 

节 ) ) 。 


你 也 可 以 基于 bean 名 称 的 模式 匹配 来 限制 自动 装配 候选 者 。 顶 级 的 <beans/> 元 
素 中 的 default-autowire-candidates 属性 接受 一 个 或 多 个 模式 。 比 如 ， 为 了 限制 自 
动 装 配 候选 者 到 任意 名 称 以 Repository 结尾 bean 的 状态 ， 提 供 *Repository 值 。 
要 提供 多 个 模式 ， 把 它们 定义 在 以 过 号 分 隔 的 列表 中 。Bean 定义 中 autowire- 
candidate 属性 的 true 或 false 明确 的 值 通 常 是 优先 的 ， 而 且 对 于 这 些 bean 来 说 ， 
模式 匹配 规则 是 不 适用 的 。 这些 技术 对 那些 永远 不 想 通 过 自动 装配 被 注入 到 其 它 
bean 中 的 bean 来 说 是 很 有 用 的 。 


这 并 不 意味 着 未 包含 的 bean 不 能 使 用 自动 装配 来 配置 。 相 反 ，bean 本 身 不 是 自动 
装配 其 它 bean 的 候选 者 。 


4.4.6 方法 注入 


在 很 多 应 用 场景 中 ， 很 多 容器 中 的 bean 是 单 例 (4.5.1 节 ) 的 。 当 一 个 单 例 的 
bean 需 要 和 其 它 单 例 的 bean 协作 时 ， 或 者 一 个 非 单 例 的 bean 需要 和 其 它 非 单 例 
的 bean 协作 时 ， 典 型 地 做 法 是 通过 定义 一 个 bean 作为 另外 一 个 的 属性 来 控制 依 
eo 5 bean 的 生命 周期 不 同时 问题 就 产生 了 。 假 设 单 例 bean A 需要 使 用 非 单 例 

(prototype， 原 型 ) bean B， 或 许 在 A 的 每 个 方法 调用 上 。 容 器 仅仅 创建 单 例 
bean A 一 次 ， 因 此 仅仅 有 一 次 机 会 去 设置 属性 。 容 器 不 能 每 次 为 bean A 提供 所 需 
的 bean B 新 的 实例 。 


解决 方法 就 是 放弃 一 些 控 制 反 转 。 你 可 通过 实现 ApplicationContextAware 接口 以 
让 bean A 去 感知 容器 (4.6.2 节 ) ， 而 且 在 每 次 bean A 需要 beanB 的 实例 时 ， 
可 以 让 容器 调用 getBean(“B”) (4.2.3 节 ) 去 获取 (一 个 新 的 ) bean B。 下 面 的 代 
码 就 是 这 种 方式 的 例子 : 


// 使 用 了 有 状态 的 命令 风格 的 类 来 执行 一 些 处 理 
package fiona.apple; 
// 导入 Spring 的 API 
import org.springframework.beans.BeansException; 
import org.springframework.context.Applicationcontext; 
import org.springframework.context .ApplicationContextAware; 
public class CommandManager implements ApplicationContextAware { 
private ApplicationContext applicationContext; 
public Object Dress (Hel? commandState) { 
// 抓 取 相 应 命令 的 新 实例 
Command command = createCommand(); 
// 在 命令 实例 上 (希望 标记 新 的 ) 设置 状态 
command.setState(commandState) ; 
return command.execute(); 


} 


protected Command createCommand() { 
// 注意 Spring API 的 依赖 ! 
return this.applicationContext.getBean("command", Comman 
d.class); 


public void setApplicationContext(ApplicationContext applica 
tionContext ) 
throws BeansException { 
this.applicationContext = applicationContext; 


前 面 的 做 法 是 不 可 eee ope 
注入 ， 这 种 Spring loC 容器 中 的 有 点 先进 的 功能 ， 允 许 以 一 种 干净 的 方式 来 处 理 
这 个 用 例 。 


你 可 以 在 博客 文章 中 来 阅读 更 多 关于 方法 注入 的 动机 。 


4.4.6.1 查找 方法 注入 


查找 方法 注入 是 容器 在 其 (eo bean 上 来 覆盖 方法 的 能 力 ， 来 返回 容器 中 其 它 命 

洛 的 查找 结果 。 ER 型 的 情况 是 涉及 原型 bean， 这 是 在 之 前 章节 中 描述 
的 情景 。Spring Framework rd CGLIB 类 库 中 ， 通 过 使 用 字 节 码 生 成 机 制 实现 了 这 
FRED > 来 动态 地 生成 覆盖 方法 的 子 类 。 


要 让 这 些 动态 子 类 起 作用 ， 在 类 路 径 下 必须 有 CGLIB 的 jar 文件。 这 些 Spring 
家 器 中 的 FRE EE 是 final 类 型 的 ， 要 被 恬 盖 的 方法 也 不 能 是 final 类 型 的 。 而 
且 ， 测 试 有 abstract 方法 的 类 要 求 你 自己 去 编写 类 的 子 类 并 提供 abstract 方法 
的 实现 。 最 后 ， 是 方法 注入 目标 的 对 象 还 不 能 被 序列 化 。 


看 一 下 之 前 代码 片段 中 的 CommandManager 类 ， 你 会 看 到 Spring 容器 会 动态 地 
和 覆盖 createCommand() 方 法 的 实现 。CommandManager 类 不 会 有 任何 Spring 的 
依赖 ， 在 重新 设计 的 例子 中 你 会 看 到 : 


package fiona.apple; 

// 没有 Spring APIA $A! 

public abstract class CommandManager { 

public Object process(Object commandState) { 

// 抓 取 一 个 心得 合适 的 Command 接 口 的 实例 
Command command = createCommand(); 
// 在 命令 实例 上 (希望 标记 新 的 ) 设置 状态 
command .setState(commandState); 
return command.execute(); 


} 
// 好 的 ..， 但 是 这 个 方法 的 实现 在 哪儿 ?3 
protected abstract Command createCommand(); 


在 客户 端 类 中 包含 要 被 注入 (Al PA CommandManager) 的 方法 ， 要 被 注入 的 
方法 需要 从 下 面 的 示例 中 编写 一 个 签名 : 


<public|protected> [abstract] <return-type> theMethodName(no-arg 
uments); 


如 果 方 法 是 abstract 的 ， 动 态 生 成 的 子 类 就 实现 这 个 方法 。 否 则 ， 动 态 生 成 的 子 类 
覆盖 定义 在 源 类 中 的 确定 方法 。 比 如 : 


<!-- 部 署 为 原型 的 〈 非 单 例 的 ) 有 状态 的 bean --> 
<bean id="command" class="fiona.apple.AsyncCommand" scope="proto 


type"> 
<!-- 注入 所 需要 的 依赖 --> 
</bean> 
<!-- commandProcessoriz% i] statefulCommandHelper - -> 


<bean id="commandManager" class="fiona.apple.CommandManager'"> 
<lookup-method name="createCommand" bean="command"/> 
</bean> 


当 需 要 command bean 的 新 的 实例 时 ， 标 识 为 commandManager 的 bean 调用 它 
自己 的 方法 createCommand()。 部 署 command bean 为 原型 的 可 必须 要 小 心 ， 那 
确实 就 是 需要 的 才 行 。 如 果 被 部 署 为 单 例 的 (4.5.1 节 ) ， 那 么 每 次 会 返回 相同 的 
command bean 的 实例 。 


~, 
提示 


感 兴 趣 的 读者 可 能 会 发 现 要 使 用 ServiceLocatorFactoryBean (在 
org.springframework.beans.factory.config 包 下 ) 。 在 
ServiceLocatorFactoryBean 中 的 使 用 的 方法 和 其 它 工具 类 是 相似 的 ， 
ObjectFactoryCreatingFactoryBean ， 但 是 它 允 许 你 去 指定 你 自己 的 查找 接口 
而 不 是 Spring 特定 的 查找 接口 。 对 这 些 类 查询 一 下 JavaDoc 文档 ， 还 有 博客 
文章 来 获取 ServiceLocatorFactoryBean 的 额外 的 信息 。 


4.4.6.2 任意 方法 的 替代 


在 方法 注入 中 ， 用 处 不 如 查找 方法 注入 大 的 一 种 形式 ， 就 是 使 用 另 Eo 
RE 换 被 容器 管理 的 bean 中 的 任意 方法 的 能 力 。 用 户 可 以 安全 地 跳 过 本 节 的 其 
部 分 ,直到 你 丨 正 需要 这 些 功能 的 时 候 来 回 过 头 来 看 。 


使 用 基于 XML 的 配置 元 数据 ， 对 于 部 署 的 bean， 你 可 以 使 用 replaced-method 元 
素来 使 用 另外 一 个 方法 替换 已 有 的 方法 实现 。 看 看 下 面 这 个 类 ， 有 一 个 我 们 想 要 去 
履 盖 的 computeValue 方法 : 


public class MyValueCalculator { 
public String computeValue(String input) { 
// EERE... 


} 
li Ere. 


实现 了 org.springframework.beans.factory.support.MethodReplacer 接口 的 类 提供 
新 的 方法 定义 。 


/** 也 就 是 要 在 MyValueCalculator 中 实现 用 来 覆盖 已 有 的 方法 
computeValue(String) 
SA 


public class ReplacementComputeValue implements MethodReplacer { 
public Object reimplement(Object o, Method m, Object[] args) 
throws Throwable { 
// 获取 输入 值 ， 并 处 理 它 ， 返 回 一 个 计算 的 结果 
String input = (String) args[0]; 


return ...; 


部 署 源 类 的 bean 定义 和 指定 的 方法 覆盖 可 以 是 这 样 的 : 


<bean id="myValueCalculator" class="x.y.z.MyValueCalculator"> 


<!-- 任意 方法 替换 --> 
<replaced-method name="computeValue" replacer="replacementCo 


mputeValue"> 
<arg-type>String</arg-type> 
</replaced-method> 
</bean> 
<bean id="replacementComputeValue" class="a.b.c.ReplacementCompu 


teValue"/> 
你 可 以 在 <replaced-method/> 元 素 中 使 用 一 个 或 多 个 包含 的 <arg-type/> 元 
素来 指示 被 覆盖 方法 的 方法 签名 。 如 果 方 法 是 被 重 载 的 并 在 类 中 有 很 多 种 形式 的 存 
字符 串 类 型 的 参数 可 能 是 类 型 全 名 的 一 


在 ， 那 么 参数 的 签名 是 必须 的 。 为 了 简便 
个 了 子囊。 比如， 下面 所 有 的 都 匹配 java.lang.String : 


java.lang.String 
String 

Str 
因为 用 参数 的 数量 用 来 区 分 每 一 个 可 能 的 选择 通常 是 足够 的 ， 这 种 快捷 方式 可 以 节 
省 大 量 的 输入 ， 人 允许 你 去 输入 匹配 参数 类 型 的 最 短 的 字符 串 。 


4.5 Bean 的 范围 


当 创 建 bean 时 ， 也 就 创建 了 对 通过 bean CVC HN AR AEL SH) MAF e bean 定 


义 的 配方 这 个 概念 是 很 重要 的 ， 因 为 它 就 意 味 着 ， 你 可 以 通过 配方 来 创建 一 个 类 的 
多 个 对 象 实例 。 
你 不 仅 可 以 控制 从 特定 bean 定义 创建 出 的 对 象 的 各 个 依赖 和 要 配置 到 对 象 中 的 


值 ， 也 可 以 控制 对 象 的 范围 。 这 个 方法 非常 强大 并 且 很 灵活 ， ， 你 可 以 选择 通过 配置 
创建 的 对 象 的 范 围 ， 而 不 必 去 处 理 Java 类 级 别 对 象 的 范围 。Bean 可 以 被 定义 部 
署 成 一 种 范围 : 开 箱 ，Spring 


Framework 支持 五 种 范围 ， 里 面 的 三 种 仅仅 通 
可 用 。 


下 列 的 范围 支持 开 箱 。 你 也 可 以 创建 自 定义 范围 (4.5.5 节 ) © 
表 4.3 Bean 的 范围 


过 感知 web 的 ApplicationContext 


范围 描述 
(BAM) 为 每 一 个 的 IOC 容器 定义 一 个 bean 为 独立 对 
(4.5.1 5 认 母 Spring 的 loc 容器 定义 bean 
节 ) 
原型 
(4.5.2 定义 可 以 有 任意 个 对 象 实例 的 bean 。 
节 ) 
请 求 定义 生命 周期 为 一 个 独立 HTTP 请 求 的 bean ; 也 就 是 说 ， 每 一 个 
(4.5.4.2 HTTP 请 求 有 一 个 bean 的 独立 的 实例 而 不 是 一 个 独立 的 bean。 仅 
节 ) 仅 在 可 感知 Web 的 Spring ApplicationContext 中 可 用 。 
rE 
4543 定义 一 个 生命 周期 为 一 个 HTTP Session 的 独立 的 bean。 仅 仅 在 
节 ) 可 感知 Web 的 Spring ApplicationContext 中 可 用 。 
全 局 会 话 ”定义 一 个 生命 周期 为 一 个 全 局 的 HTTP Session 的 独立 的 bean。 
(4.5.4.4 HH 型 地 是 仅仅 使 用 portlet 上 下文 时 可 用 。 仅仅 在 可 感知 Web 
节 ) 的 Spring ApplicationContext 中 可 用 。 


线程 范围 的 bean 


在 Spring 3.0 当中 ， 线 程 范围 是 可 用 的 ， 但 是 它 默 认 是 不 注册 的 。 "要 获取 更 多 信 
息 ， 请 BA SimpleThreadSc ope 的 JavaDoc 文档 。 对 于 如 何 注 册 这 个 范围 或 其 
它 自 定义 范 围 的 做 法 ? 


请 参考 4.5.5.2 节 ，“ 使 用 自 定义 范围 ”。 


4.5.1 2%) ck 


仅仅 共享 被 管理 的 bean 人 实例 ， 所 有 使 用 一 个 或 多 个 id 来 匹配 bean 的 结果 
对 bean 请 求 ， 由 Spring 容器 返回 指定 bean 的 实例 。 


另外 一 种 方式 ， 当 你 定义 一 个 范围 是 单 例 的 bean 后 ，Spring 的 loC 容器 通过 
bean 的 定 义 创 建 了 这 个 对 象 的 一 个 实例 。 这 个 独立 的 实例 存储 在 单 例 bean By 
存 中 ， 所 有 对 这 个 命 名 bean 的 后 续 的 请 求 和 引用 都 返回 缓存 的 对 象 。 








| .. and this same shared instance is injected into each collaborating object | 











Spring 中 对 单 例 bean 的 概念 和 四 人 帮 (Gang of Four ， GoF) 设计 模式 书 中 定义 
的 单 例 模式 是 不 同 的 。GoF 的 单 例 硬 编码 了 对 象 的 范围 ， ， 也 就 是 特定 的 类 仅仅 能 
有 一 个 实例 被 每 一 个 ClassLoader 来 创建 。Spring 中 单 例 bean 的 范围 ， 是 对 每 一 
个 容器 和 bean 来 说 的 。 这 就 意味 着 在 独立 的 Spring 容器 中 ， 对 一 个 特定 的 类 创 
建 了 一 个 bean， 那 么 Spring 容 器 通过 过 bean 的 定义 仅仅 创建 这 个 类 的 一 个 实例 。 

在 Spring 中 ， 单 例 范 围 是 默认 的 范围 。 要 在 XML 中 定义 单 例 的 bean， 可 以 按照 
如 下 示例 来 编写 : 


<bean id="accountService" class="com.foo.DefaultAccountService"/ 
> 


<!-- 尽管 是 元 余 的 ( 单 例 范围 是 默认 的 ) ， 下 面 的 bean 定 义 和 它 是 等 价 的 --> 
<bean id="accountService" class="com. foo.DefaultAccountService" 
scope="Singleton"/> 


4.5.2 原型 范围 


非 单 例 ， 原 型 范围 的 bean 就 是 当 每 次 对 指定 bean 进行 请 求 时 ， 一 个 新 的 bean 的 
实例 Ave 建 。 也 就 是 说 ，bean 被 注入 到 其 它 bean 或 是 在 容器 中 通过 getBean() 
方法 来 请 求 时 就 会 创建 新 的 bean 实例 。 作为 一 项 规则 ， 对 所 有 有 状态 的 bean 使 
用 原型 范围 ， 而 对 于 无 状 态 的 bean 使 用 单 例 范 围 。 


下 图 讲述 了 Spring 的 原型 范围 。 数 据 访问 对 象 《DAO ) 通常 不 是 配置 成 原型 的 ， 
因为 典型 的 DAO 不 会 持 有 任何 对 话 状 态 ; 仅仅 是 对 作者 简单 对 单 例 图 的 重用 。 





(oe | A brand new bean instance is created... 
cS ara i oe : — iis a | | 
scope="prototype” /> 


... each and every time the prototype is referenced by collaborating beans | 








下 面 的 示例 在 XML 中 定义 了 原型 范围 的 bean : 


<!-- 使 用 Spring-beans-2.0.dtd --> 
<bean id="accountService" class="com. foo.DefaultAccountService" 
scope="prototype"/> 


和 其 它 范围 相 比 ，Spring 不 管理 原型 bean 的 完整 生命 周期 ; 容器 实例 化 ， 配 置 并 
装配 原型 对 象 ， 并 把 他 给 客户 端 对 于 原型 bean 的 实例 来 说 ， 就 没有 进一步 的 跟 
踪 记 录 了 。 因 此 ， 尽 管 初始 化 生命 周期 回调 方法 可 以 对 所 有 对 象 调用 而 不 管 范围 ， 
那么 在 原型 范围 中 ， 配 置 销毁 生命 周期 回调 是 不 能 被 调用 的 。 客 户 端 代码 必须 清理 
原型 范围 的 对 象 并 且 释 放 原 型 bean 持 有 的 系统 资源 。 要 让 Spring 容器 来 释放 原型 
范围 bean 持 有 的 资源 ， 可 以 使 用 自 定义 bean 后 处 理 器 (4.8.1 节 ) ， 它 持 有 需要 
被 清理 的 bean 的 引用 。 


在 某 些 方面 ， 关 于 原型 范围 bean 的 Spring 容器 的 角色 就 是 对 Java new 操作 符 的 
替代 。 所 有 之 后 生命 周期 的 管理 必须 由 客户 端 来 处 理 。 (关于 Spring 容器 中 bean 
的 生命 周期 的 详细 内 容 ， 可 以 参考 4.6.1 节 ，“ 生 命 周 期 回调 ”) 


4.5.3 单 例 bean 和 原型 bean 依赖 


当 你 使 用 单 例 范 围 的 bean 和 其 依赖 是 原型 范围 的 bean 时 ， 要 当心 依赖 实在 实例 
化 时 被 解析 的 。 因 此 ， 如 果 依 赖 注 入 了 原型 范围 的 bean 到 单 例 范围 的 bean 中 ， 
新 的 原型 bean 就 被 实例 化 并 且 依 赖 注入 到 单 例 bean 中 。 原 型 实例 是 唯一 的 实例 
并 不 断 提 供给 单 例 范围 的 bean ° 

假设 你 想 单 例 范围 的 bean 在 运行 时 可 以 重复 获得 新 的 原型 范围 bean 的 实例 。 那 
么 就 不 能 将 原型 范围 的 bean 注入 到 单 例 bean 中 ， 因 为 这 个 注入 仅仅 发 生 一 次 ， 
就 是 在 Spring 容器 实例 化 单 例 bean 并 解析 和 注入 它 的 依赖 时 。 如 果 你 在 运行 时 需 
要 原型 bean 新 的 实例 而 不 是 仅仅 一 次 ， 请 参考 4.4.6 节 ，“ 方 法 注入 ”。 


4.5.4 请 来 ， 会 话 和 全 局 会 话 范围 


request > session 和 global session 范围 仅仅 当 你 使 用 感知 Web 的 Spring 
ApplicationContext 实现 类 可 用 ee ° fie 果 你 在 党 
规 的 Spring loC 容器 中 使 用 如 ClassPathXmlApplicationContext 这 范围 ， 那 么 
就 会 因为 一 个 未 知 的 bean 的 范围 而 得 到 IllegalStateException # % 


4.5.4.1 初始 化 Web 配置 


要 支持 request，session 和 global session 级 别 (Web 范围 的 bean) 范围 的 
bean ° 一 些 细微 的 初始 化 配置 置 就 需要 在 定义 bean 之 前 来 做 。 (这 些 初 始 化 的 设置 
对 标准 的 范围 ， 单 例 和 原型 ， 是 不 需要 的 。) 


如 果 来 完成 这 些 初 始 化 设置 是 基于 你 使 用 的 特定 Servlet 容器 的 。 


如 果 使 用 Spring 的 Web MVC 来 访问 这 些 范围 的 bean， 实 际 上 ， 是 由 Spring 的 
DispatcherServlet 或 DispatcherPortlet 来 处 理 请 求 的 ， 那 就 没有 特殊 的 设置 了 : 
DispatcherServlet 和 DispatcherPortlet 已 经 可 以 访问 所 有 相关 的 状态 。 


如 果 你 使 用 支持 Servlet 2.4 规范 以 上 的 Web 容器 ， 在 Spring 的 
DispatcherServle (比如 ， 当 使 用 JSF 或 Struts 时 ) 之 外 来 处 理 请 求 ， 那 
么 就 需要 添加 javax.servlet.ServletRequestListener 到 Web 应 用 的 web.xml 文 
件 的 声明 中 : 


<web -app> 


<listener> 
<listener-class> org.springframework.web.context.request 
.RequestContextLi 
stener 
</listener-class> 
</listener> 


</web-app> 


如 果 你 使 用 老 版 的 Web 容器 ( Serlvet 2.3 ) > a A 3 1k 用 提供 的 
javax.servlet.Filter 实现 类 。 如 果 你 想 在 Servlet 2.3 248 ¥ > 在 Spring 的 
DispatcherServlet 外 部 的 请 求 中 访问 Web 范围 的 bean， 下 面 的 XML 配置 代码 片 
RELA E AE Web 应 用 程序 的 web.xml 文件 中 。 (过 滤器 映射 基于 所 处 的 
Web 应 用 程序 配置 ， 所 以 你 必须 以 适当 的 形式 来 修改 它 。) 


<web -app> 


<filter> 
<filter -name>requestContextFilter</filter -name> 
<filter-class>org.springframework.web.filter.RequestCont 

extFilter</filter-class> 

</filter> 

<filter -mapping> 
<filter -name>requestContextFilter</filter -name> 
<url-pattern>/*</url-pattern> 

</filter -mapping> 


</web-app> 


DispatcherServlet > RequestContextListener 和 RequestContextFilter 所 有 都 可 以 
做 相同 的 事情 ， 即 绑 定 HTTP 请 求 对 象 到 服务 于 请 求 的 Thread 中。 这 使 得 bean 
在 请 求 和 会 话 范围 内 对 后 续 的 调用 链 可 用 。 


4.5.4.2 请 求 范围 
考虑 一 下 下 面 的 bean 定义 : 


<bean id="loginAction" class="com.foo.LoginAction" scope="reques 
TE WAS 


Spring 容器 通过 使 用 LoginAction bean 的 定义 来 为 每 个 HTTP 请 求 创建 
LoginAction bean 的 新 的 实例 。 也 就 是 说 ，LoginAction bean 是 在 HTTP 请 求 级 别 
的 范围 。 你 可 以 改变 创建 的 实例 内 部 的 状态 ， 怎 么 改 都 可 以 ， 因 为 从 相同 的 
LoginAction bean 定义 中 创建 的 其 它 实例 在 状态 上 不 会 看 到 这 些 改变 ; 它们 对 单独 
的 请 求 都 是 独立 的 。 当 请 求 完成 处 理 ，bean 在 请 求 范围 内 被 丢弃 了 。 


4.5.4.3 会 话 范 围 
考虑 一 下 下 面 的 bean 定义 : 


<bean id="userPreferences" class="com.foo.UserPreferences" scope 
="session"/> 


Spring 容器 通过 使 用 UserPreferences bean 的 定义 来 为 每 个 HTTP 会 话 的 生命 周 
期 创建 UserPreferences bean 的 新 的 实例 。 换 和 句 话说 ，UserPreferences bean 在 
HTTP 


session 级 别 的 范围 内 是 有 效 的 。 正 如 request-scoped 的 bean， 你 可 以 改变 创建 
的 实例 内 部 的 状态 ， 怎 么 改 都 可 以 ， 要 知道 其 它 HTTPsession 实例 也 是 
使 用 从 相同 UserPreferences bean 的 定义 中 创建 的 实例 ， 它 们 不 会 看 到 状态 的 改 


变 ， 因 为 它们 对 单 独 的 HTTP session 都 是 独立 的 。 当 HTTP session 最 终 被 丢弃 
> 那么 和 这 个 HTTP session 相关 的 bean LZA T ° 


4.5.4.4 全 局 会 话 范 围 
考虑 一 下 下 面 的 bean 定义 : 


<bean id="userPreferences" class="com.foo.UserPreferences" scope 
="globalSession"/> 


global session 范围 和 标准 的 HTTP Session 范围 《上 面 4.5.4.3 节 讨 论 的 ) 类 似 ， 
但 仅 能 应 用 于 基于 portlet 上 下 文 的 Web 应 用 程序 。 pol 规范 定义 了 全 局 的 
Session 的 概念 ， RABE AA portlet 之 间 所 共享 来 构建 一 个 单独 的 oe Web 
应 用 程序 。 在 global session 范围 内 定义 的 bean 的 范围 (约束 ) 就 会 在 全 局 
portlet Session 的 生命 周期 内 。 


如 果 你 编写 了 一 个 标准 的 基于 Servlet 的 Web 应 用 ， 并 且 定义 了 一 个 或 多 个 有 
global session 范围 的 bean， 那 么 就 会 使 用 标准 的 HTTP Session 范围 ， 也 不 会 抛 
出 什么 错误 。 


4.5.4.5 各 种 范围 的 bean 作为 依赖 


Spring 的 loC 容器 不 仅仅 管理 对 象 (bean) 的 实例 ， 而 且 也 装配 协作 者 ( 依 

赖 ) 。 如 果 你 想 注入 (上 比如) 一 个 HTTP 请 求 范围 的 bean 到 另外 一 个 bean 中 ， 
那么 就 必须 在 有 范围 bean 中 注入 一 个 AOP 代理 。 也 就 是 说 ， 你 需要 注入 一 个 代 
理 对 象 来 公开 相同 的 公共 接口 作为 有 范围 的 对 象 ， 这 个 对 象 也 可 以 从 相关 的 范围 
(比如 ，HTTP 请 求 范围 ) PREAH AM 象 并 且 委托 方法 调用 到 真正 的 对 象 
a 


i 


立 


注意 
你 不 需要 使 用 <aop:scoped-proxy/> 来 结合 singleton 和 prototype 范围 的 
bean 。 如 果 你 想 为 单 例 bean 裳 试 创建 有 范围 的 代理 ， 那 么 就 会 
Ja 出 BeanCreationException $% ° 


在 下 面 的 示例 中 ， 配 置 仅 仅 只 有 一 行 ， 但 是 这 对 理解 “为 什么 "和 其 中 的 “怎么 做 "是 至 
关 重 要 的 。 


<?xml version="1.0" encoding="UTF-8"?> 
<beans xmlns="http://www.springframework.org/schema/beans" xmins 
>xsi="http://www.w3.org/2001/XMLSchema -instance" xmlns:aop="htt 
p://www.springframework.org/schema/aop" xsi:schemaLocation="http 
://www.springframework.org/schema/beans http://www. springframewo 
rk.org/schema/beans/spring -beans-3.0.xsd http://www. springframe 
work.org/schema/aop http://www.springframework.org/schema/aop/sp 
ring -aop-3.0.xsd"> 
<!-- HTTP 会 话 范围 的 bean 作 为 代理 --> 
<bean id="userPreferences" class="com.foo.UserPreferences" s 
cope="Session"> 
<!-- 这 个 元 素 影响 周围 bean 的 代理 --> 
<aop: scoped-proxy/> 
</bean> 
<!-- 单 例 范围 的 bean 用 上 面 的 代理 bean 来 注入 --> 
<bean id="userService" class="com.foo.SimpleUserService"> 
<!-- 作为 代理 的 userPreferences bean 引 用 --> 
<property name="userPreferences" ref="userPreferences"/> 
</bean> 
</beans> 


要 创建 这 样 的 代理 ， 就 要 插入 一 个 子 元 素 <aop:scoped-proxy/> 到 有 范围 的 
bean 的 定义 中 。 (如 果 要 选择 基于 类 的 代理 ， 那 么 需要 在 类 路 径 下 放置 CGLIB 的 
类 库 ， 参 考 下 面 的 “选择 创建 代理 类 型 "部 分 和 “附录 C， 基 于 XML Schema 的 配 
置 ") 为 什么 request ，session，globalSession 和 自 定义 范围 级 别 的 bean 需 

要 <aop:scoped-proxy/> 元 素 ? 我 们 来 看 看 下 面 的 单 例 bean 定义 ， 并 将 它 和 你 
需要 定义 的 上 述 范围 来 比较 一 下 。 (下 面 的 userPreferences bean 的 定义 是 不 完 
整 的 。) 


<bean id="userPreferences" class="com.foo.UserPreferences" scope 
="session"/> 
<bean id="userManager" class="com.foo.UserManager"> 

<property name="userPreferences" ref="userPreferences"/> 
</bean> 


在 上 面 的 例 子 中 ， 单 例 bean userManager < HTTP session 范围 的 bean 
userPreferences 的 引用 注入 的 。 这 里 突出 的 一 点 就 是 ene bean 是 单 例 
的 ; 那么 对 于 每 个 容器 来 说 ， 它 只 会 被 实例 化 一 次 ， 并且 它 的 依赖 (本 例 中 只 有 一 
个 依赖 ， 就 是 UserPreferences bean) 也 只 会 被 注入 一 次 。 这 就 意味 着 
userManager bean 只 会 对 同 一 个 userPreferences 对 象 进行 操作 ， 也 就 是 说 ， 是 
最 初 被 注入 的 那 一 个 对 象 。 


这 并 不 是 你 想 要 的 行为 ， 即 注入 生命 周期 范围 短 的 bea n 到 生命 周期 范围 长 的 bea 
n 中 ， 注入 HTTP session 范围 的 协作 bean TEA RB 到 1 bean ¥ ° 4 
ae 尔 需 要 一 个 单独 的 userManager + % > 4 « JA HA 4e HTTP session — 4 
你 需要 一 个 userPreferences 对 象 来 特定 于 HTTP session。 因 此 容器 创建 对 
7 公开 相同 的 公共 接口 ， 而 UserPreferences 类 (理想 情况 下 是 
UserPreferences 实例 的 对 象 ) 从 范围 机 制 (HTTP 请 求 ，session 等 等 ) KARR 


正 的 UserPreferences 对 象 。 容 器 注入 这 个 代理 对 象 到 userManager bean 中 ， 这 
个 bean 不 能 感知 UserPreferences 的 引用 就 是 代理 。 在 这 个 示例 中 ， 当 
UserManager 实例 调用 依赖 注入 的 UserPreferences 对 象 的 方法 时 ， 那 么 其 实 是 
在 代理 上 调用 这 个 方法 。 然 后 代理 从 〈 在 本 例 中 ) HTTP session 中 RRA 
UserPreferences 对 象 ， 并 且 委 托 方法 调用 到 获取 的 丨 实 的 UserPreferences 对 象 
Po 


因此 ， 当 注入 request 范围 ，session 范围 和 globalSession 范围 的 bean 到 协作 对 
象 时 ， 你 需要 下 面 的 ， 正 确 的 ， 完 整 的 配置 : 


<bean id="userPreferences" class="com.foo.UserPreferences" scope 


="session"> 
<aop:scoped-proxy/> 
</bean> 


<bean id="userManager" class="com.foo.UserManager"> 
<property name="userPreferences" ref="userPreferences"/> 
</bean> 


选择 创建 代理 类 型 


默认 情况 下 ， 当 Spring 容器 为 被 <aop:scoped-proxy/> 元 素 标记 的 bean 创建 

代理 时 ， 基 于 CGLIB 的 类 的 代理 就 被 创建 了 。 这 就 是 说 在 应 用 程序 的 类 路 径 下 需 
要 有 CGLIB 的 类 库 。 注意 : CGLIB 代理 仅仅 拦截 公有 的 方法 调用 ! 不 会 调用 代理 
中 的 非 公 有 方法 ; 它们 不 会 被 委托 到 有 范围 的 目标 对 象 。 


另外 ， 你 可 以 配置 Spring 容器 有 范围 的 bean 创建 标准 的 基于 IDK 接口 的 代理 > 
通过 指定 <aop:scoped-proxy/> 元 素 的 proxy-target-class 属性 值 为 false。 使 用 
基于 JDK 接口 的 代理 意味 着 你 不 需要 在 应 用 程序 的 类 路 径 下 添加 额外 的 类 库 来 使 
代理 生效 。 然 而 ， 它 也 意味 着 有 范围 bean 的 类 必须 实现 至 少 一 个 接口 ， 并 且 注 入 
到 有 范围 bean 的 所 有 协作 者 必须 通过 它 的 一 个 接口 来 引用 bean 。 


<!-DefaultUserPreferences 实 现 了 UserpPreferences 接 口 --> 
<bean id="userPreferences" class="com.foo.DefaultUserPreferences 
" scope="sSession"> 

<aop:scoped-proxy proxy-target-class="false"/> 
</bean> 
<bean id="userManager" class="com.foo.UserManager"> 

<property name="userPreferences" ref="userPreferences"/> 
</bean> 


关于 选择 基于 类 或 基于 接口 的 代理 的 更 多 详细 信息 ， 可 以 参考 86 节 ，“ 代 理 机 
Ail” o 


4.5.5 自 定 义 范 围 


在 Spring 2.0 当中 ，bean 的 范围 机 制 是 可 扩展 的 。 你 可 以 定义 自己 的 范围 ， 或 者 
重新 定 义 已 有 的 范围 ， 尽 管 后 者 被 认为 是 不 良 实践 而 且 你 不 能 覆盖 内 建 的 
singleton 和 prototype 范围 。 


4.5.5.1 创建 自 定义 范围 


要 整合 自 定 义 范 围 到 Spring 的 容器 中 ， 那 么 需要 实现 
org.springframework.beans factory.config.Scope 接口 ， 这 会 在 本 节 中 来 介绍 。 对 
于 如 何 实现 你 自己 的 范围 的 想法 ， 可 以 参考 Spring Framework 本 身 提供 的 Scope 
实现 和 Scope 的 JavaDoc 文 档 ， 这 里 会 介绍 你 需要 实现 的 方法 的 更 多 细节 。 


Scope UM 围 中 获取 对 象 ， 从 作用 域 范围 中 移 除 对 象 还 有 
允 许 它 们 被 销毁 。 


下 面 的 方法 从 底层 范围 中 返回 对 象 。 比 如 ， 会 话 夺 包围 的 实现 ， 返 回 会 话 站 € A a9 
bean (如 果 它 不 存在 ， 在 绑 定 到 会 话 后 为 将 来 的 引用 ， 这 个 方法 返回 bean 的 新 的 
实例 ) 。 


Object get(String name, ObjectFactory objectFactory) 


下 面 的 方法 从 底层 范围 中 移 除 对 象 。 比 如 会 话 范围 的 实现 ， 从 底层 的 会 话 中 移 除 
话 范围 的 bean。 对 象 应 该 被 返回 ， 但 0 A a ds 
返回 null ° 


Object remove(String name) 


下 面 的 方法 注册 当 被 销毁 或 者 指定 范围 内 的 对 象 被 销毁 时 ， 相 关 范 围 应 用 执行 的 回 


调 函 数 。 参 考 JavaDoc 文档 或 者 Spring 范围 实现 来 获取 更 多 关于 销毁 回调 的 信 
息 fe} 


void registerDestructionCallback(String name, Runnable destructi 
onCallback) 


下 面 的 方法 得 到 一 底层 范围 的 会 话 标识 符 。 这 个 标识 符 对 每 种 范围 都 是 不 同 的 。 
对 于 Sis i ere > 这 个 标识 符 可 以 是 会 话 标识 符 。 


String getConversationId() 


4.5.5.2 使 用 自 定 义 范 围 


在 你 编写 并 测试 一 个 或 多 个 自 定 义 Scope 实现 之 后 ， 你 需要 让 Spring 容器 感知 你 
的 新 的 范围 。 下 面 的 方法 是 用 Spring 容器 注册 新 的 Scope 的 核心 方法 。 


void registerScope(String scopeName, Scope scope); 


这 个 方法 在 oring PIER Anr Soony 接口 中 声明 ， 也 在 大 多 数 的 
ApplicationContext 实现 类 中 可 用 ， 通 过 BeanFactory 属性 跟着 Spring ° 


一 个 参数 是 和 范围 相关 的 唯一 名 称 ; 在 Spring 容器 本 身 
he 


registerScope(..) 方 法 的 第 
参数 是 你 


这 样 的 名 字 就 是 singleton 和 prototype ° registerScope(..)7 i= 49 FH —*4 
想 注 册 并 使 用 的 自 定 义 Scope KILLA A R Hl o 


假设 你 编写 了 自 定义 的 Scope 实现 ， 之 后 便 如 下 注册 了 它 。 


D 


ca 


iz2 
下 面 的 示例 使 用 了 SimpleThreadScope ， 这 是 包含 在 Spring 当中 的 ， 但 模式 
是 没有 注册 的 。 这 些 指 令 和 你 自己 自 定义 的 Scope 的 实现 是 相同 的 。 


Scope threadScope = new SimpleThreadScope(); beanFactory.registe 


rScope("thread", threadScope); 


之 后 就 可 以 为 你 的 自 定义 Scope 创建 符合 Spring 规则 的 bean 的 定义 : 


<bean id="..." class="..." scope="thread"> 


使 用 自 定义 的 Scope 实现 ， 并 没有 被 限制 于 程序 注册 。 你 也 可 以 进行 声明 式 的 


Scope 注 册 ， 使 用 CustomScopeConfigurer 类 : 


<?xml version="1.0" encoding="UTF-8"?> 
<beans xmlns="http://www.springframework.org/schema/beans" xmlns 
>xsi="http://www.w3.org/2001/XMLSchema -instance" xmlns:aop="htt 
p://www.springframework.org/schema/aop" xsi:schemaLocation="http 
://www. springframework.org/schema/beans http://www. springframewo 
rk.org/schema/beans/spring -beans-3.0.xsd 
http://www. springframework.org/schema/aop http://www.springframe 
work.org/schema/aop/spring -aop-3.0.xsd"> 
<bean 
class="org.springframework.beans.factory.config.CustomSc 
opeC onfigurer"> 
<property name="Scopes"> 
<map> 
<entry key="thread"> 
<bean class="org.springframework.context.sup 
port.SimpleT hreadScope"/> 
</entry> 
</map> 
</property> 
</bean> 
<bean id="bar" class="x.y.Bar" scope="thread"> 
<property name="name" value="Rick"/> 
<aop:scoped-proxy/> 
</bean> 
<bean id="foo" class="x.y.Foo"> 
<property name="bar" ref="bar"/> 
</bean> 
</beans> 


i 
EEA 


4 72 FactoryBean 的 实现 中 放置 <aop:scoped-proxy/> 时 ， 那 就 是 工厂 
bean 本 身 被 放 置 到 范围 中 ， 而 不 是 从 getObject() 方 法 返回 的 对 象 。 


4.6 自 定 义 bean 的 性 质 


4.6.1 生命 周期 回调 


为 了 和 容器 管理 bean 的 生命 周期 进行 交互 ， 你 可 以 实现 Spring 的 InitializingBean 
和 DisposableBean 接口 。 容 器 为 前 者 调用 afterPropertiesSet() 方 法 ， 为 后 者 调 用 
destroy() 方 法 在 bean 的 初始 化 和 销毁 阶段 允许 bean 执行 特定 的 动作 。 你 也 可 以 
和 容 器 达到 相同 的 整合 ， 而 不 需要 通过 使 用 初始 化 方法 和 销毁 方法 的 对 象 定义 元 数 
据 来 耦合 你 的 类 到 Spring 的 接口 中 。 


从 内 部 来 说 ，Spring Framework 使 用 了 BeanPostProcessor 的 实现 来 处 理 任何 回 
调 接口 ， 它 可 以 发 现 并 调用 合适 的 方法 。 如 果 你 需要 自 定义 特性 或 其 它 生 命 周期 行 
为 ，Spring 不 会 提供 开 箱 ， 你 可 以 自行 实现 BeanPostProcessor 接口 。 要 获取 更 
多 信息 ， 可 以 参考 4.8 节 ，" 容 器 扩展 点 "。 


除了 初始 化 和 销毁 回调 ，Spring 管理 的 对 象 也 会 实现 Lifecycle 接口 ， 所 以 那些 对 
象 可 以 参与 到 启动 和 关闭 过 程 ， 来 作为 容器 自己 的 生命 周期 。 


生命 周期 回调 接口 在 本 节 中 来 说 明 。 


4.6.1.1 初始 化 回调 


org.springframework.beans.factory.InitializingBean 接口 允许 bean 在 所 有 必须 的 
属性 被 容器 设置 完成 之 后 来 执行 初始 化 工作 。|nitializingBean 接口 中 仅仅 指定 了 一 
个 方法 : 


void afterPropertiesSet() throws Exception; 


推荐 不 要 使 用 InitializingBean 接口 ， 因 为 它 不 必要 地 将 代码 耦合 到 Spring Po A 
外 ， 可 以 指定 一 个 POJO 初始 化 方法 。 在 基于 XML 配置 元 数据 的 情形 中 ， 你 可 以 
使 用 init-method 属性 来 指定 签名 为 无 返回 值 ， 无 参数 的 方法 的 名 称 。 上 比如， 下 面 
的 定义 : 


<bean id="exampleInitBean" 
class="examples.ExampleBean" 
init-method="init"/> 
public class ExampleBean { 
public void init() { 
// 做 一 些 初 始 化 工作 
} 


这 和 下 面 的 做 法 是 完全 相同 的 : 


<bean id="exampleInitBean" 
class="examples.AnotherExampleBean"/> 
public class AnotherExampleBean implements InitializingBean { 
public void afterPropertiesSet() { 
// 做 一 些 初始 化 工作 
} 


但 是 没有 耦合 任何 代码 到 Spring 中 。 
4.6.1.2 销毁 回调 


实现 org.springframework.beans.factory.DisposableBean 接口 ， 当 容器 包含 的 
bean #44 SN > ATE RAW ° DisposableBean 接口 中 仅仅 有 一 个 方法 : 


void destroy() throws Exception; 


推荐 不 要 使 用 DisposableBean 接口 ， 因 为 它 不 必要 地 将 代码 耦合 到 Spring Po 4 
外 ， 可 以 指定 一 个 由 bean 支持 的 通用 的 方法 。 使 用 基于 XML 配置 元 数据 ， 你 可 
以 使 用 <bean/> 元 素 中 的 destroy-method 属性 。 上 比如， 下 面 的 定义 : 


<bean id="exampleInitBean" 
class="examples.ExampleBean" 
destroy-method="cleanup"/> 
public class ExampleBean { 
public void cleanup() { 
// 做 一 些 销毁 工作 (比如 释放 连接 池 的 连接 ) 
} 


这 和 下 面 的 做 法 是 完全 相同 的 : 


<bean id="exampleInitBean" 
class="examples.AnotherExampleBean"/> 
public class AnotherExampleBean implements DisposableBean { 
public void destroy() { 
// 做 一 些 销毁 工作 (比如 释放 连接 池 的 连接 ) 
} 


但 是 没有 耦合 代码 到 Spring 中 。 


4.6.1.3 默认 的 初始 化 和 销毁 方法 


当 使 用 Spring 指定 的 InitializingBean 和 DisposableBean 回调 接口 来 编写 初 始 化 
和 销毁 方法 回调 时 ， 典 型 地 做 法 就 是 编写 名 称 为 init()，initialize()，dispose() 等 方 
法 .理想 的 情况 ， 这 样 的 生命 周期 回调 方法 的 名 称 在 一 个 项 目 中 是 标准 化 的 ， 那 么 所 
有 的 开发 人 员 可 以 使 用 相同 的 方法 名 称 来 保证 一 致 性 。 


你 可 以 配置 Spring 容器 在 每 个 bean 中 来 查看 命名 的 初始 化 和 销毁 回调 方法 名 称 。 
这 就 是 说 ， 作 为 应 用 程序 开发 人 员 ， 你 可 以 编写 应 用 类 并 且 使 用 初始 化 回调 方法 
ee 而 不 需要 在 每 个 bean 的 定义 中 来 配置 init-method="init" 属 性 。 当 bean 被 
创建 时 (并 按 照 前 面 描 gt at ai 周期 回调 合约 ) > Spring 的 loc 容器 调用 
这 个 方法 。 这 个 特性 也 对 初始 化 和 销毁 方法 回调 强制 执行 了 一 致 的 命名 约定 。 


假设 你 的 初始 化 回调 方法 命名 为 init()， 销 毁 回调 方法 命名 为 destroy()。 尔 就 
可 以 按照 如 下 示例 来 装 配 类 : 


public class DefaultBlogService implements BlogService { 
private BlogDao blogDao; 
public void setBlogDao(BlogDao blogDao) { 
this.blogDao = blogDao; 


} 
// ZA (WAER) 初始 化 回调 方法 
public void init() { 
if (this.blogDao == null) { 
throw new IllegalStateException("The [blogDao] prope 
rty must be set."); 


} 
} 


<beans default-init-method="init"> 
<bean id="blogService" class="com.foo.DefaultBlogService"> 
<property name="blogDao" ref="blogDao" /> 
</bean> 
</beans> 


顶层 <beans/> 元 素 的 default-init-method 属性 的 存在 ， 就 会 让 Spring 的 loC & 
器 意识 到 在 bean 中 的 一 个 叫做 init 的 方法 就 是 初始 化 回调 方法 。 当 一 个 bean 被 创 
建 和 装 配 时 ， 如 果 bean 类 有 这 样 一 个 方法 ， 那 么 它 就 会 在 合适 的 时 间 被 调用 。 


相似 地 (也 就 是 在 XML 中 )， 你 可 以 使 用 顶层 元 素 <beans/> 的 default- 
destroy-method 属性 来 配置 销毁 回调 方法 。 


在 已 经 存在 的 bean 类 中 ， 有 命名 差异 的 回调 方法 ， 你 可 以 指定 (也 就 是 在 XML 
+) ” <bean/> 本 身 的 init-method 和 destroy-method 属性 来 覆盖 默认 的 方法 。 


Spring 容器 保证 了 在 给 bean 提供 所 有 的 依赖 后 置 的 初始 化 回调 方法 会 立即 被 
调用 。 A sean te 回调 也 被 称 为 原始 的 oe | ee aa AOP 的 拦截 器 等 
尚未 应 用 到 bean 中 。 目 标 bean 首先 被 完全 创建 ， 之 后 AOP 代理 (比方 说 ) 
的 拦截 器 链 就 会 被 应 用 上 © 


如 果 目 标 bean 和 代理 分 开 来 定义 了 ， 你 的 代码 仍然 可 以 绕 开 代理 和 原始 目标 bea 
n 来 交互 。 因 此 ， 引 用 拦截 器 到 初始 化 方法 中 会 是 不 一 致 的 ， 因为 这 么 来 做 了 会 和 
它 的 代理 /拦截 耦合 目标 bean 的 合生 命 周 期 ， 当 你 的 代码 直接 和 原始 目标 bean X 
互 时 ， 会 留 下 奇怪 的 语义 。 


4.6.1.4 组 合生 命 周期 机 制 


在 Spring 2.5 中 ， 对 控制 bean 的 生命 周期 行为 有 三 种 选择 : 

InitializingBean (4.6.1.1 节 ) 和 DisposableBean (4.6.1.2 节 ) 回调 接口 ; 自 定义 
init() 和 destroy() 方 法 ; @PostConstruct 4e@PreDestroy 注解 (4.9.6 7) 。 你 可 
以 组 合 这 些 机 制 来 控制 给 定 的 bean e 


如 果 对 一 个 bean 配置 了 多 个 生命 周期 机 制 ， 并 且 每 种 机 制 都 用 不 同 的 方法 名 
称 来 配置 ， 那 么 每 个 配置 方法 就 会 以 下 面 列 出 的 顺序 来 执行 。 然 而 ， 如 果 配 置 
Se ee 
那么 这 个 方法 就 执行 一 次 ， 这 在 前 面 章节 解释 过 了 。 


相同 的 bean 配置 了 不 同 初始 化 方法 的 多 个 生命 周期 机 制 ， 那 么 就 按 下 面 顺序 调 
用 : 


e 使 用 @PostConstruct 注解 的 方法 
e  InitializingBean 回调 接口 定义 的 afterPropertiesSet() 方 法 


自 定义 配置 的 init() 方 法 销毁 方法 也 是 同样 顺序 调用 : 


e 使 用 @PreDestroy 注解 的 方法 
e 由 DisposableBean 回调 接口 定义 的 destroy () 方 法 
e 自 定义 配置 的 destroy () 方 法 


4.6.1.5 启动 和 关闭 回调 


tenes 接口 定义 了 对 于 任意 有 它 自己 生命 周期 需求 ( 比如， 开始 和 结束 一 些 后 合 
FZ) 对 象 的 必要 方法 : 


public interface Lifecycle { 
void start(); 
void stop(); 
boolean isRunning(); 


任何 Spring 管理 的 对 象 可 以 实现 这 个 接口 。 那 么 ， 当 ApplicationContext 本 身 局 
人 een eee 
给 LifecycleProcessor 来 做 : 


public interface LifecycleProcessor extends Lifecycle { 
void onRefresh(); 
void onClose(); 


要 注意 LifecycleProcessor AY x7 KT Lifecycle 接口 。 而 且 它 添加 了 两 个 方法 
来 对 上 下 文 的 刷新 和 关闭 做 出 反应 。 


启动 和 关闭 调用 的 顺序 是 很 重要 的 。 如 果 一 个 “依赖 "关系 存在 于 两 个 任意 对 象 间 ， 
那 么 需要 依赖 的 一 方 会 在 它 的 依赖 启动 之 后 启动 ， 并 且 在 它 的 依赖 关闭 之 前 停止 。 
然而 ， 有 时 直接 的 依赖 关系 是 未 知 的 。 你 可 能 仅仅 知道 确定 类 型 的 对 象 应 该 优先 于 
另外 一 种 类 型 对 象 的 启动 。 在 那些 情形 下 ，SmartLifecycle 接口 定义 了 另外 一 种 选 
择 ， 命 名 为 getPhase() 方法 ， 在 它 的 父 接口 Phased 中 来 定义 。 


public interface Phased { 
int getPhase(); 


public interface SmartLifecycle extends Lifecycle, Phased { 
boolean isAutoStartup(); 
void stop(Runnable callback); 


当 启 动 时 ， 最 低层 的 对 象 首先 启动 ， 当 停止 时 ， 是 相反 的 。 因 此 
， 实 现 了 SmartLifecycle 接口 ， 并 且 getPhase() 方 法 返回 IntegerMIN_VALUE 
的 对 象 就 会 在 最 先 开 始 和 最 后 停止 的 中 间 。 在 范围 的 另外 一 端 ， 
Integer.MIN_VALUE 的 层次 值 表 示 对 象 应 该 最 后 启动 并 且 最 先 停止 (可 能 是 因为 
它 取决 于 其 它 进程 的 执行 ) 。 当 考虑 层次 值 时 ， 知 道 任 意 “ 普 通 " 对 象 并 且 没 有 实现 
Lifecycle 接口 的 默认 的 层次 是 0， 这 也 是 很 重要 的 。 因 此， 任意 负 的 层次 值 就 表示 
对 象 应 该 在 那些 标准 组 件 之 前 启动 (在 它们 之 后 停止 ) ， 对 于 任意 正 的 层次 值 ， 反 
之 亦 然 。 


正如 你 看 到 由 SmartLifecycle 定义 的 停止 方法 接收 回调 。 任 何 实现 类 必须 在 实现 类 
关闭 进程 完成 之 后 ， 调 用 回调 方法 run()。 这 使 得 必要 时 可 以 进行 异步 关闭 ， 因 为 黑 
认 的 LifecycleProcessor 接口 的 实现 ，DefaultLifecycleProcessor， 会 等 待 每 个 阶 
段 一 组 对 疹 来 调用 回调 的 超时 值 。 每 个 阶段 的 默认 超时 是 30 秒 。 你 可 以 在 上 下 文 
中 定义 名 为 “lifecycleProcessor” 的 bean 来 覆盖 默认 的 生命 周期 进程 实例 。 如 果 你 
仅仅 想 去 修改 超时 时 间 ， 那 么 定义 下 面 的 bean 就 足够 了 : 


<bean id="lifecycleProcessor" class="org.springframework.context 
.support.DefaultLifecycleProc essor"> 

<!-- 毫秒 数 的 超时 时 间 --> 

<property name="timeoutPerShutdownPhase" value="10000"/> 
</bean> 


正如 所 提 到 的 ，LifecycleProcessor 接口 定义 了 刷新 和 关闭 上 下 文 的 回调 方法 。 后 
者 将 驱动 关闭 进程 ， 就 好 像 明确 地 调用 了 stop() 方 法 ， 但 是 当 上 下 文 关闭 时 它 才 会 
发 生 。 另 一 方面 ，' 刷 新 ' 回 调 使 得 SmartLifecycle bean 的 另外 一 个 特性 可 用 。 当 上 
下 文 刷 新 时 (在 所 有 对 象 都 被 实例 化 和 初始 化 后 ) ， 才 会 调用 回调 方法 ， 在 那 时 ， 
默认 的 生命 周期 进程 会 检查 每 个 SmartLifecycle 对 象 的 isAutoStartup() 方 法 返回 的 
布尔 值 。 。 如 果 是 是 “true”， 那 时 对 象 将 会 被 启动 ， 而 不 是 等 待 明确 的 上 下 文 调用 或 它 自 
己 的 start() 方 法 (不 像 上 下 文书 新 ， 对 标准 的 上 下 文 实现 来 说 ， 上 下 文 启动 不 会 自 
动 发 生 ) 。"“ 阶 段 " 值 和 任意 “ 依 赖 "关系 会 按照 上 面 所 描述 的 相同 方式 来 决定 启动 的 
MRAP ° 


4.6.1.6 在 非 Web 应 用 中 ， 优 雅 地 关闭 Spring loC 容器 
i 


本 节 仅 对 非 Web 应 用 来 说 。 在 相关 Web 应 用 程序 关闭 时 ， » Spring aT 


Web 的 ApplicationContext 实现 已 经 有 代码 来 优雅 地 关闭 Spring 的 loc 容器 
了 。 


果 你 在 非 Web 应 用 环境 中 使 用 Spring 的 loC 容器 ; 比如 ， 在 富 客户 端 桌面 环境 
i 你 在 JVM 中 注册 了 一 个 关闭 的 钓 子 。 这 么 来 做 就 保证 了 优雅 地 关闭 并 且 在 单 
例 bean 中 调用 相关 销毁 方法 ， 那 么 所 有 资源 都 会 被 释放 。 当 然 ， 你 必须 正确 配置 
并 实现 这 些 销毁 回调 方法 。 要 注册 一 个 关闭 钧 子 ， 可 以 调用 
AbstractApplicationContext 类 中 声明 的 registerShutdownHook() 方 法 : 


import org.springframework.context.support.AbstractApplicationCo 
ntext; import org.springframework.context.support.ClassPathXmlAp 
plicationConte xt; 
public final class Boot { 

public static void main(final String[] args) throws Exce 
ption { AbstractApplicationContext ctx 

= new ClassPathXmlApplicationContext(new String []{" 

beans.xml"}); 

// 对 上 面 的 上 下 文 添加 一 个 关闭 的 钩子 . . ， 

ctx.registerShutdownHook(); 

// 这 里 运行 应 用 程序 . . ， 

// 主 方 法 退出 ， 钧 子 在 应 用 关闭 前 优先 被 调用 . . ， 


4.6.2 ApplicationContextAware 和 BeanNameAware 


4 ApplicationContext 创建 实现 了 
org. springframework.context.ApplicationContextAware 接口 的 类 时 ， 这 个 类 就 被 
提供 了 一 个 ApplicationContext 的 引用 。 


public interface ApplicationContextAware { 
void setApplicationContext(ApplicationContext applicationCon 
text) throws BeansException; 


} 


因此 bean 就 可 以 编程 来 操作 创建 它们 的 ApplicationContext ， 通 过 
ApplicationContext 接口 ， 或 者 转换 到 这 个 接口 的 已 知 子 类 型 ， 比 如 
ConfigurableApplicationContext， 会 公开 更 多 的 功能 。 一 种 使 用 方式 就 是 编程 式 获 
取 其 它 的 bean。 有 时 候 这 种 能 力 是 很 有 用 的 。 然 而 ， 通 常 你 应 该 避免 这 么 来 做 ， 
因为 它 会 耦合 代码 到 Spring 中 ， 还 没有 协作 者 作为 属性 提供 给 bean 的 控制 反 转 的 
风格 。 应 用 上 下 文 的 其 它 方法 提供 了 访问 文件 资源 ， 公 共 应 用 事件 和 访问 消息 资源 
的 方法 。 这 些 补充 特性 为 在 4.14 节 ，“ 应 用 上 下 文 的 补充 功能 "来 说 明 。 


在 Spring 2.5 中 ， 自 动 装配 是 获取 ApplicationContext 引用 的 另外 一 种 方式 。“ 传 
统 的 "constructor 和 byType 自动 装配 模式 (在 4.4.5 7 ，" 自 动 装配 协作 者 "中 说 明 
的 ) 可 以 分 别 为 构造 方法 参数 或 setter 方法 参数 提供 ApplicationContext 类 型 的 依 
赖 。 为 了 更 大 的 灵活 性 ， 包 括 自动 装配 字段 和 多 参数 方法 的 能 力 ， 还 有 使 用 新 的 基 
于 注解 的 自动 装 配 特 性 。 如 果 字 段 ， 构 造 方法 或 者 普通 方法 进行 @Autowired 注 
解 ， 而 且 你 这 么 做 了 ，ApplicationFactory 就 会 自动 装配 到 期 望 BeanFactory 类 型 
的 字段 ， 构 造 方法 参数 或 方法 参数 。 要 获取 更 多 信息 ， 可 以 参考 4.9.2 

节 ，“@Autowired #7 @Inject” ° 

当 应 用 上 下 文 创建 实现 了 


org.springframework.beans.factory.BeanNameAware 接口 的 类 时 ， 这 个 类 会 被 提 
供 一 个 在 相关 对 象 中 定义 的 命名 引用 。 


public interface BeanNameAware { 
void setBeanName(string name) throws BeansException; 


} 


回调 函数 在 普通 bean 的 属性 被 填充 之 后 并 且 在 如 InitializingBean 的 
afterPropertiesSet 或 自 定 义 初始 化 方法 的 初始 化 回调 之 前 被 调用 。 


4.6.3 其 它 Aware 接口 


除了 上 面 讨 论 的 ApplicationContextAware 和 BeanNameAware，Spring 还 提供 了 

很 多 Aware 接口 ， 它 们 允许 bean 来 告诉 容器 它们 需要 确定 的 基础 的 依赖 。 最 重要 
的 Aware 接口 在 下 面 总 结 出 来 了 -作为 一 个 通用 的 规则 ， 名 称 就 很 好 地 说 明了 依赖 

的 类 型 : 


表 4.4 Aware 接口 
名 称 注入 的 依赖 何 处 解释 


4.6.2 7°“ 
ApplicationContextAware 
和 BeanNameAware” 


声明 


ApplicationContextA ware ApplicationContext 


ApplicationEventPub 
lisherAware 


BeanClassLoaderAware 


BeanFactoryAware 


BeanNameAware 


BootstrapContextAwa re 


LoadTimeWeaverAware 


MessageSourceAware 


NotificationPublisherAware 


PortletConfigAware 


PortletContextAware 


包含 在 
ApplicationContext 
内 的 事件 发 布 


用 于 加 载 bean 类 
的 类 加 载 器 


声明 BeanFactory 


声明 bean 的 名 称 


Aa] 


器 运行 的 资源 适 


BootstrapContext ° 
典型 地 是 仅仅 在 
JCA 感知 的 
ApplicationContext 
a a ie 


在 加 载 时 为 处 理 类 
定义 的 织 入 器 


解析 消息 配置 的 策 
略 (支持 参数 化 和 
际 化 ) 


Spring JMX 通知 发 
布 


容器 运行 的 当前 
的 PortletConfig ° 
仅 在 感知 Web 的 
Spring 的 
ApplicationContext 


` 


A 


容器 运行 的 当前 
的 PortletContext 。 
仅 在 感知 Web 的 
Spring 的 
ApplicationContext 
中 有 效 


4.147 2 AERP SH 
Ah Fe Hy a6” 


4.3.2 $ > “实例 化 bean” 


AOD te 
ApplicationContextA 
ware 和 
BeanNameAware” 


462 F>“ 
ApplicationContextA 
ware 和 
BeanNameAware” 
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8.8.4 ¥ > “Spring 
Framework P 4% M 
Aspect J 进行 加 载 时 织 
次 


4.14% >“ AEP SH 
补充 功能 ” 
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第 19 È > Portlet MVC 
框架 


ResourceLoaderAware 


ServletConfigAware 


ServletContextAware 


为 低级 别 的 资源 访 
问 配 置 的 加 载 器 


容器 运行 的 当前 
的 ServletConfig ° 
仅 在 感知 Web 的 
Spring 的 
ApplicationContext 
中 有 效 


容器 运行 的 当前 
的 ServletContext 。 
仅 在 感知 Web 的 
Spring 的 
ApplicationContext 


第 5 章 ， 资 源 


16 章 ，Web MVC 框 


We Be 


第 16 = > Web MVC 框 


Ta FL KE FBSA ARA R] Spring API 的 这 些 接口 的 使 用 ， 并 不 再 遵循 控制 反 转 风 


格 。 


因此 ， 它 们 被 推荐 使 用 到 基础 的 bean 中 ， 那 些 bean 需要 编程 式 地 访问 容器 。 


4.7 Bean 定义 的 继承 


bean 的 定义 可 以 包含 很 多 配置 信息 包括 构造 方法 参数 ， 属 性 值 和 容器 指定 的 信 

息 ， 比 如 初始 化 方法 ， 静 态 工 厂 方法 名 称 等 。 子 bean 定义 继承 从 父 bean 中 获得 
的 配置 元 数据 。 子 bean 可 以 覆盖 一 些 值 或 者 添加 其 它 所 需要 的 。 使 用 父子 bean 
定义 可 以 节省 很 多 输入 。 实际 上 ， 这 是 一 种 模板 形式 。 


如 果 你 编程 式 地 使 用 ApplicationContext 接 口 ， 子 bean 的 定义 可 以 由 
ChildBeanDefinition 类 代表。 很 多 AP 不 使 用 这 个 级 别 的 方法 ， 而 是 在 RM 
于 ClassPathXmlApplicationContext. 中 声明 式 地 配置 bean 的 信息 。 当 使 用 基于 
XML 的 配置 元 数据 时 ， 你 可 以 使 用 parent 属性 来 标识 一 个 子 bean， 使 用 这 个 属性 
的 值 来 标识 父 bean。 


<bean id="inheritedTestBean" abstract="true" class="org.springfr 
amework.beans.TestBean"> 

<property name="name" value="parent"/> 

<property name="age" value="1"/> 

</bean> 

<bean id="inheritswithDifferentClass" class="org.springframework 
.beans.DerivedTestBean" parent="inheritedTestBean" init-method=" 
initialize"> 

<property name="name" value="override"/> 

<!-- age 属性 值 1 将 会 从 父 bean 中 继承 过 来 --> 

</bean> 


如 果 没 有 指定 一 个 子 bean 使 用 父 bean 的 类 ， 但 也 可 以 覆盖 它 。 在 这 种 情形 中 ， 
子 bean 的 类 必须 和 父 bean 兼容 ， 也 就 是 说 ， 它 必须 接受 父 bean 的 属性 值 。 


F bean 的 定义 继承 构造 方法 参数 值 ， 属 性 值 ， 还 有 父 bean 的 方法 覆盖 ， 添 加 新 
值 的 选择。 任何 你 指定 的 初始 化 方法 ， 销 毁 方 法 ， 和 /或 static 工厂 方法 设置 会 履 
盖 对 应 父 bean 中 的 设置 。 


剩 下 的 设置 通常 是 从 子 bean 来 定义 : 依赖 ， 自 动 装配 模式 ， 依 赖 检 测 ， 单 例 ， 范 
> KEIR ASL © 


前 面 的 示例 明确 地 使 用 了 abstract 属性 来 标识 了 父 bean 的 定义 。 如 果 父 bean 没 
有 指定 类 ， 那 么 明确 地 标识 父 bean 就 必须 要 有 abstract， 如 下 所 示 : 


<bean id="inheritedTestBeanwithoutClass" abstract="true"> 
<property name="name" value="parent"/> 
<property name="age" value="1"/> 
</bean> 
<bean id="inheritswWithClass" class="org.springframework.beans.De 
rivedTestBean" parent="inheritedTestBeanwithoutClass" 
init-method="initialize"> 
<property name="name" value="override"/> 
<!-- age 属性 值 1 将 会 从 父 bean 中 继承 过 来 --> 
</bean> 


X bean 不 会 被 实例 化 ， 因 为 它 自己 是 不 完整 的 ， 而 且 也 明确 地 被 abstract 标记 。 
当 bean 的 定义 是 abstract 这 样 的 ， 那 么 它 也 仅仅 被 用 做 纯 bean 定义 的 模板 ， 作 
AF bean 定义 的 父 bean。 尝 试 使 用 这 种 自身 是 abstract 的 父 bean， 作 为 另外 一 
个 bean 参考 的 属 性 来 指 代 它 ， 或 者 使 用 父 bean 的 id 来 明确 使 用 getBean() 方 法 
调用 ， 会 返回 错误 。 相 似 地 ， 容 器 内 部 的 prelnstantiateSingletons() 方 法 忽略 了 抽 
象 bean 的 定义 。 

i 


注意 

默认 情况 下 ， 预 实例 化 所 有 单 例 bean。 因 此 ， 如 果 你 有 仅仅 想 用 作 模 板 的 

( 父 ) bean， 而 且 这 个 bean 指定 了 一 个 类 ， 那 么 必须 将 abstract 属性 设置 六 
true， 这 点 是 很 重要 的 。 否 则 ， 应 用 上 下 文 就 会 (尝试 ) 预 实例 化 abstract 的 
bean ° 


48 容器 扩展 点 


通常 情况 下 ， 应 用 程序 开发 人 员 不 需要 编写 ApplicationContext 实现 类 的 子 类 。 相 
反 ，Spring 的 IloC 容器 可 以 通过 插件 的 方式 来 扩展 ， 就 是 实现 特定 的 整合 接口 。 下 
面 的 几 个 章节 会 来 说 明 这 些 整合 接口 。 


4.8.1 使 用 BeanPostProcessor 来 自 定 义 bean 


BeanPostProcessor 接口 定义 了 你 可 以 提供 实现 你 自己 的 〈 或 覆盖 容器 默认 的 ) 实 
例 远 辑 ， 依 赖 解析 逻辑 等 的 回调 方法 。 如 果 你 想 在 Spring 容器 完成 实例 化 ， 配 置 
和 初始 化 bean 之 后 实现 一 些 自 定义 逻辑 ， 那 么 你 可 以 使 用 一 个 或 多 个 
BeanPostProcessor 实现 类 的 插件 。 


你 可 以 配置 多 个 BeanPostProcessor 实例 ， 而 且 你 还 可 以 通过 设置 order 属性 来 
控制 这 些 BeanPostProcessor 执行 的 顺序 。 4 24 BeanPostProcessor 实现 了 
Ordered 接口 你 才 可 以 设置 设 个 属性 ; 如 果 你 想 编写 你 自己 的 
BeanPostProcessor， 你 也 应 该 考虑 实现 Ordered 接口 。 要 了 解 更 多 细节 > 
可 以 参考 JavaDoc 文档 中 的 BeanPostProcessor 和 Ordered 接口 。 


BeanPostProcessor 操作 bean 〈 对 象 ) 实例 ; 那 也 就 是 说 ，Spring 的 loC 容 
器 实例 化 bean 的 实例 ， 之 后 BeanPostProcessor 来 做 它们 要 做 的 事情 。 


BeanPostProcessor 的 范围 是 对 于 每 一 个 容器 来 说 的 。 如 果 你 使 用 了 容器 继承 ， 那 
么 这 才 有 所 关联 。 如 果 你 在 一 个 容器 中 定义 了 BeanPostProcessor’ ®A e412 会 
在 那个 容器 中 后 处 理 bean。 换 和 句 话说， 一 个 容器 中 定义 的 bean 不 会 被 另外 一 个 容 
器 中 定义 的 BeanPostProcessor 来 进行 后 处 理 ， 即 便 是 两 个 容器 都 是 相同 继承 链 
上 的 一 部 分 。 


要 修改 扶正 的 bean 定义 (也 就 是 说 ， 定 义 bean HRA) ， 你 可 以 使 用 4.8.2 

节 ，“ 使 用 BeanFactoryPostProcessor 来 自 定 义 配 置 元 数据 "描述 的 
BeanFactoryPostProcessor 来 进行 。 
org.springframework.beans.factory.config.BeanPostProcessor 接口 由 两 个 回调 方 
法 构成 。 如 果 在 容器 中 有 一 个 类 注册 为 后 处 理 器 ， 对 于 容器 创建 的 每 个 bean 的 实 
例 ， 后 处 理 器 从 容器 中 获得 回调 方法 ， 在 容器 初始 化 方法 之 前 ( 比如 
InitializingBean 的 afterPropertiesSet() 方 法 和 任意 声明 为 初始 化 的 方法 ) 被 调用 ， 
ZAE bean 初始 化 回调 之 后 被 调用 。 后 处 理 器 可 以 对 bean 实例 采取 任何 动作 ， 
包括 完整 忽略 回调 。 通 常 来 说 bean 的 后 处 理 器 会 对 回调 接口 进行 检查 ， 或 者 会 使 
用 代理 包装 bean ° 一些 Spring 的 AOP 基 类 也 会 作为 bean 的 后 处 理 器 实现 来 提 
供 代理 包装 逻辑 。 


ApplicationContext 会 自动 检测 任意 实现 了 BeanPostProcessor 接口 的 bean 定义 
的 配置 元 数据 。ApplicationContext 注册 这 些 bean 作为 后 处 理 器 ， 那 么 它们 可 以 
在 bean 创建 之 后 被 调用 。Bean 的 后 处 理 器 可 以 在 容器 中 部 署 ， 就 像 其 它 bean I 


样 。 
BeanPostProcessor 和 AOP 自动 代理 


实现 了 BeanPostProcessor 接口 的 类 是 特殊 的 ， 会 被 容器 不 同 对 待 。 所 有 它们 参照 
的 BeanPostProcessor 和 bean 会 在 启动 时 被 实例 化 ， 作 为 


ApplicationContext 启 动 阶段 特殊 的 一 部 分 。 接 下 来 ， 所 有 的 
BeanPostProcessor 以 排序 的 方式 注册 并 应 用 于 容器 中 的 其 它 bean。 因 为 AOP A 
动 代理 作为 BeanPostProcessor 本 身 的 实现 ， 它 们 为 自动 代理 资格 的 直接 引用 的 
既 不 是 BeanPostProcessor 也 不 是 bean， 因 此 没有 织 入 它们 的 方面 。 


对 于 这 样 的 bean， 你 应 该 看 到 一 个 信息 级 的 日 志 消 息 :“Bean foo 没有 由 所 有 
BeanPostProcessor 接口 处 理 的 资格 (比如 : 没有 自动 代理 的 资格 ) ”。 下 面 的 示 
例 展 示 了 如 何在 ApplicationContext 中 编写 ， 注 册 和 使 用 BeanPostProcessor ° 


4.8.1.1 示例 : BeanPostProcessor 风格 的 Hello World 


第 一 个 示例 说 明了 基本 的 用 法 。 示 例 展 示 了 一 个 自 定 义 的 BeanPostProcessor 实现 
类 来 调用 每 个 由 容器 创建 bean 的 toString() 方 法 并 打印 出 字符 串 到 系统 的 控制 台 
wo 


自 定 义 BeanPostProcessor 实现 类 的 定义 : 


package scripting; 
import org.springframework.beans.factory.config.BeanPostProcesso 
r; 
import org.springframework.beans.BeansException; 
public class InstantiationTracingBeanPostProcessor implements 
BeanPostProcessor { 

// 简单 地 返回 实例 化 的 bean 

public Object postProcessBeforeInitialization(Object bean, S 
tring beanName)throws BeansException { 

return bean; // 这 里 我 们 可 能 返回 任意 对 象 的 引用 .,， 


public Object postProcessAfterInitialization(Object bean, St 
ring beanName)throws BeansException { 


System.out.printin("Bean '" + beanName + "' created : " 
+ 
bean. toString()); 
return bean; 
} 
} 


<?xml version="1.0" encoding="UTF-8"?> 
<beans xmlns="http://www.springframework.org/schema/beans" xmins 
:xsi="http://www.w3.0rg/2001/XMLSchema -instance" xmlns:lang="ht 
tp://www.springframework.org/schema/lang" xsi:schemaLocation="ht 
tp://www.springframework.org/schema/beans http://www.springframe 
work.org/schema/beans/spring -beans-3.0.xsd http://www.springfra 
mework.org/schema/lang http://www. springframework.org/schema/lan 
g/spring-lang-3.0.xsd"> 
<lang:groovy id="messenger" 
script-source="classpath:org/springframework/scripting/g 
r oovy/Messenger .groovy"> 
<lang:property name="message" value="Fiona Apple Is Just 
So 
Dreamy. "/> 
</lang:groovy> 
alas 
当 上 面 的 pean(messenger) 被 实例 化 时 ， 这 个 自 定 义 的 BeanPostProcessor 实 
现 会 输出 实际 内 容 到 系统 控制 台 
3 
<bean 
class="scripting.InstantiationTracingBeanPostProcessor" /> 
</beans> 


注意 InstantiationTracingBeanPostProcessor 仅仅 是 简单 地 定义 。 它 也 没有 命名 ， 
为 它 会 像 其 它 bean 那样 被 依赖 注入 。 (前 面 的 配置 也 可 以 定义 成 Groovy 脚本 
支持 的 bean。Spring 2.0 动态 语言 支持 在 第 27 章 中 来 详细 说 明 ) 


下 面 示例 的 Java 应 用 程序 执行 了 前 面 配 置 的 代码 : 


import org.springframework.context.ApplicationContext; 
import org.springframework.context.support.ClassPathXmlApplicati 
onConte xt; 
import org.springframework.scripting.Messenger; 
public final class Boot { 
public static void main(final String[] args) throws Exceptio 
nt 
ApplicationContext ctx = new 
ClassPathXmlApplicationContext("scripting/beans. xml" 
); 
Messenger messenger = (Messenger) ctx.getBean("messenger 
"); System.out.println(messenger); 


} 


上 面 应 用 程序 的 输出 类 似 于 如 下 内 容 : 


Bean 'messenger' created : org.springframework.scripting.groovy. 
GroovyMessenger@272961 org.springframework.scripting.groovy.Groo 
vyMessenger@272961 


4.8.1.2 示例 : RequiredAnnotationBeanPostProcessor 


配合 自 定义 的 BeanPostProcessor 实现 使 用 回调 接口 或 者 注解 ， 是 扩展 Spring loC 

容器 的 一 种 通用 方式 。Spring 的 RequiredAnnotationBeanPostProcessor 就 是 一 个 

例子 一 一 种 BeanPostProcessor 实现 ， 随 着 Spring 一 起 发 布 ， 来 保证 bean 中 被 
(任意 ) 注解 所 标记 的 JavaBean BE AE (ACR) 注入 时 有 值 。 


4.8.2 使 用 BeanFactoryPostProcessor 自 定 义 配 置 元 数据 
下 一 个 扩展 点 我 们 要 来 看 看 


org.springframework.beans.factory.config.BeanFactoryPostProcessor 。 这 个 接口 
的 语义 和 那 些 BeanPostProcessor 是 相 似 的 ， 但 有 一 个 主要 的 不 同 点 : 
BeanFactoryPostProcessor 操作 bean 的 配置 元 数据 ; 也 就 是 说 Spring 的 loC È 
器 允许 BeanFactoryPostProcessor 来 读 取 配 置 元 数据 并 在 容器 实例 化 
BeanFactoryPostProcessor 以 外 的 任何 bean 之 前 可 以 修改 它 。 


你 可 以 配置 多 个 BeanFactoryPostProcessor， 并 且 你 也 可 以 通过 order 属性 来 控 
制 这 2 BeanFactoryPostProcessor 执行 的 顺序 。 然 而 ， 仅 当 
BeanFactoryPostProcessor 实现 Ordered 接口 时 你 才能 设置 这 个 属性 。 如 果 编 写 
你 自己 的 BeanFactoryPostProcessor， 你 也 应 该 考虑 实现 Ordered 接口 。 参 考 
JavaDoc 文档 来 获取 BeanFactoryPostProcessor 和 Ordered 接口 的 更 多 细节 。 


YE 
to RARE BEA bean 实例 (也 就 是 说 ， 从 配置 元 数据 中 创建 的 对 象 ) ， 
那么 你 需要 使 用 BeanPostProcessor (在 上 面 4.8.1 ¥ > “2M 
BeanPostProcessor 来 自 定 义 bean "中 描述 ) 来 代替 。 在 
BeanFactoryPostProcessor (比如 使 用 BeanFactory.getBean()) 中 来 使 用 这 
些 bean 的 实例 虽然 在 技术 上 有 是 可 行 的 ， 12 这么 来 做 会 引起 bean TF KH 
化 ， 速 反 标 准 的 容器 生命 周期 。 这 也 会 引发 一 些 副作用 ， 比如 绕 过 bean 的 后 
处 理 。 


而 且 ，BeanFactoryPostProcessor 的 范围 也 是 对 每 一 个 容器 来 说 的 。 如 果 你 使 用 
TÈ 器 的 继承 的 话 ， 这 就 是 唯一 相关 的 点 了 。 如 果 你 在 一 个 容器 中 定义 
了 BeanFactoryPostProcessor， 那 么 它 只 会 用 于 在 那个 容器 中 的 bean。 一 个 容器 
中 Bean 的 定义 不 会 被 另外 一 个 容器 中 的 BeanFactoryPostProcessor 后 处 理 ， 即 
便 两 个 容器 都 是 相同 继承 关系 的 一 部 分 。 


当 在 ApplicationContext 中 声明 时 ，bean 工厂 后 处 理 器 会 自动 被 执行 ， 这 就 可 以 
对 定义 在 容器 中 的 配置 元 数据 进行 修改 。Spring 包含 了 一 些 预定 义 的 bean 工厂 后 
XZ > kete PropertyOverrideConfigurer 和 PropertyPlaceholderConfigurer. ° 4 
定义 的 BeanFactoryPostProcessor 也 可 以 来 有 用， 比如， 注册 自 定 义 的 属性 编辑 


0 
aa 


ApplicationContext 会 自动 检测 任意 部 署 其 中 ， 且 实现 了 
BeanFactoryPostProcessor 接口 的 bean。 在 适当 的 时 间 ， 它 用 这 些 bean 作为 
bean 工厂 后 处 理 器 。 你 可 以 部 署 这 些 后 处 理 器 bean 作为 你 想 用 的 任意 其 它 的 
bean。 


和 BeanPostProcessor 一 样 ， 通 第 你 不 会 想 配 置 BeanFactoryPostProcessor 
来 进行 延迟 初始 化 。 如 果 没 有 其 它 bean 引用 Bean(Factory)PostProcessor > 
那么 后 处 理 器 就 不 会 被 初始 化 了 。 因 此 ， 标 记 它 为 延迟 初始 化 就 会 被 忽略 ， 即 
IRIRE <beans/> 元 素 声 明 中 设置 default-lazy-init AHA true > #8 2 
Bean(Factory)PostProcessor 也 会 正常 被 初始 化 。 


4.8.2.1 示例 : PropertyPlaceholderConfigurer 


你 可 以 使 用 来 对 使 用 了 标准 Java Properties 格式 的 分 离 文件 中 定义 的 bean 来 声明 
属 性 值 。 这 么 来 做 可 以 使 得 部 署 应 用 程序 来 自 定义 指定 的 环境 属性 ， 比 如 数据 库 的 
连接 URL 和 密码 ， 不 会 有 修改 容器 的 主 XML 定义 文件 或 其 它 文件 的 复杂 性 和 风 


险 。 
考虑 一 下 下 面 这 个 基于 XML 的 配置 元 数据 代码 片段 ， 这 里 的 dataSource 就 使 用 了 


占 位 符 来 定义 。 这 个 示例 展示 了 从 Properties 文件 中 配置 属性 的 方法 。 在 
运行 时 ，PropertyPlaceholderConfigurer 就 会 用 于 元 数据 并 为 数据 源 替 换 一 些 属 


TE o JEZA 换 的 值 作 为 ${ 属 性 -名 } 形 式 中 的 占 位 符 ， 这 里 应 用 了 Ant/log4j/JSP EL 
的 风格 。 


<bean class="org.springframework.beans.factory.config.PropertyPl 
aceho lderConfigurer"> 
<property name="locations" value="classpath:com/foo/jdbc.pro 
perties"/> 
</bean> 
<bean id="dataSource" destroy-method="close" class="org.apache.c 
ommons.dbcp.BasicDataSource"> 
<property name="driverClassName" value="${jdbc.driverClassNa 
me}"/> 
<property name="url" value="${jdbc.url}"/> 
<property name="username" value="${jdbc.username}"/> 
<property name="password" value="${jdbc.password}"/> 
</bean> 


aE A) fi eK AT 4a 424) Java Properties 格式 的 文件 : 


jdbc.driverClassName=org.hsqldb.jdbcDriver 
jdbc.url=jdbc:hsqldb:hsql://production: 9002 
jdbc.username=sa 

jdbc.password=root 


因此 ， 字 符 串 $fjdbc.username} 在 运行 时 会 被 值 'Sa' 替 换 ， 对 于 其 它 占 位 符 来 说 也 是 
相同 的 ， 匹 配 到 了 属性 文件 中 的 键 就 会 用 其 值 蔡 换 占 位 符 。 
PropertyPlaceholderConfigurer 在 很 多 bean 定义 的 属性 中 检查 占 位 符 。 此 外 ， 对 
占 位 符 可 以 自 定义 前 级 和 后 级 。 


使 用 Spring 2.5 引入 的 context 命名 空间 ， 也 可 以 使 用 专用 的 配置 元 素来 配置 属性 
占 位 符 。 在 location 属性 中 ， 可 以 提供 一 个 或 多 个 以 逗号 分 隔 的 列表 。 


<context:property-placeholder 
location="classpath:com/foo/jdbc.properties"/> 


PropertyPlaceholderConfigurer 不 仅仅 查看 在 Properties 文件 中 指定 的 属 性。 默认 
情况 下 ， 如 果 它 不 能 在 指定 的 属性 文件 中 发 现 属性 ， 它 也 会 检查 Java System 属 
性 。 你 可 以 通过 设置 systemPropertiesMode 属性 ， 使 用 下 面 整数 的 三 者 之 一 来 自 
定义 这 种 行为 : 


never(0) : 从 不 检查 系统 属性 


fallback(1) : 如 果 没 有 在 指定 的 属性 文件 中 解析 到 属性 ， 那 么 就 检查 系统 属性 。 这 
ER 认 的 情况 。 


override(2) : 在 检查 指定 的 属性 文件 之 前 ， 首 先 去 检查 系统 属性 。 这 就 允许 系统 属 
ER 盖 其 它 任意 的 属性 资源 。 


查看 PropertyPlaceholderConfigurer 的 JavaDoc 文档 来 获取 更 多 信息 。 
类 名 替换 


你 可 以 使 用 ee th 来 替换 类 名 ， 在 运行 时 ， 当 你 不 得 不 去 
选择 一 个 特定 的 实现 类 时 ， 这 是 很 有 用 的 。 比 如 : 


<bean class="org.springframework.beans.factory.config.PropertyPl 
ac eholderConfigurer"> 
<property name="locations"> 
<value>classpath:com/foo/strategy.properties< /value> 
</property> 
<property name="properties"> 
<value>custom.strategy.class=com.foo.DefaultStrategy< / 
value> 
</property> 
</bean> 
<bean id="serviceStrategy" class="${custom.strategy.class}"/> 


如 果 类 在 运行 时 不 能 解析 成 一 个 有 效 的 类 ， 那么 在 即将 创建 时 ，bean 的 解析 就 失 
败 了 ， 这 是 ApplicationContext 在 对 非 延 迟 初 始 化 bean 的 
prelnstantiateSingletons() 阶 段 发 生 的 。 


4.8.2.2 示例 : PropertyOverrideConfigurer 


PropertyOverrideConfigurer ， 另 外 一 种 bean 工 厂 后 处 理 器 ， 类 似 于 
PropertyPlaceholderConfigurer， 但 不 像 后 者 ， 对 干 所 有 bean 的 属性 ， 原 始 定义 
可 以 有 默认 值 或 没有 值 。 如 果 一 个 Properties A á LIAA A E bean 的 属性 配置 
Ho RA 就 会 使 用 默认 的 上 下 文 定义 。 


注意 ，bean 定义 是 不 知道 被 覆盖 的 ， 所 以 从 XML 定义 文件 中 不 能 立即 明显 反应 履 
BR 置 。 在 多 个 PropertyOverrideConfigurer 实例 的 情况 下 ， 为 相同 bean 的 属性 
定义 不 同 的 值 ， 那 么 最 后 一 个 有 效 ， 这 就 是 覆盖 机 制 。 属性 文件 配置 行 像 这 种 格 
式 : 


beanName.property=value 
比如 : 


dataSource.driverClassName=com.mysql.jdbc.Driver dataSource.url= 
jdbc:mysql:mydb 


这 个 示例 文件 可 以 用 于 包含 了 dd data ou bean 的 容器 ， 它 有 driver 和 url 属性 。 
复合 属性 名 也 是 支持 的 ， 除 了 最 终 的 属性 被 覆盖 ， 只 要 路 径 中 的 每 个 组 件 都 是 非 空 
的 (假设 由 构造 方法 初始 化 )。 在 这 个 例子 中 


foo ,fred.bob.sammy=123 


„foo bean 的 fred 属性 的 bob 属性 的 sammy 属性 的 值 设置 为 标量 123。 注意 指 
定 的 覆盖 值 通常 是 文字 值 ; 它们 不 会 被 翻译 成 bean 的 引用 。 当 XML 中 的 bean 定 
义 的 原始 值 指 定 了 bean 引用 时 ， 这 个 约定 也 适用 。 


使 用 Spring 2.5 引入 的 context 命名 空间 ， 可 以 使 用 专用 的 配置 元 素来 配置 属性 履 


x 
im. 


<context:property-override 
location="classpath: override.properties"/> 


4.8.3 使 用 FactoryBean 来 自 定义 实例 化 逻辑 


实现 了 org.springframework.beans.factory.FactoryBean 接口 的 对 象 它们 就 是 自己 
的 工厂 。 


FactoryBean 接口 就 是 Spring loC 容器 实例 化 逻辑 的 可 插 拔 点 。 如 果 你 Wl 
码 ae ， 那么 相对 于 (潜在 地 ) 大 量 详细 的 XML 而 言 ， 最 好 是 使 用 Java 语言 

来 表达 。 你 可 以 创建 自己 的 FactoryBean ， 在 类 中 编写 复杂 的 初始 化 代码 ， 之 
后 将 你 自 定义 的 FactoryBean 插入 到 容器 中 。 


FactoryBean 接口 提供 下 面 三 个 方法 : 


Object PoU 返回 工厂 创建 对 象 的 实例 。 这 个 实例 可 能 被 共享 ， 那 就 是 看 这 
个 工厂 返回 的 是 单 例 还 是 原型 实例 了 。 

boolean ns ingleron > 如 果 FactoryBean 返回 单 例 的 实例 ， 那 么 该 方法 返回 
true ， 否 则 就 返回 false。 


Class getObjectType() : 返回 由 getObject() 方 法 返回 的 对 象 类 型 ， 或 者 事先 不 知 道 
类 型 时 返回 null。 


FactoryBean 的 概念 和 接口 被 用 于 Spring Framework 中 的 很 多 地 方 ; 随 Spring 发 
行 ， 有 超过 50 个 FactoryBean 接口 的 实现 类 。 


当 你 需要 向 容器 请 求 一 个 真实 的 FactoryBean 实例 ， 而 不 是 它 生产 的 bean， 当 调 
用 ApplicationContext 的 getBean() 方 法 时 ， 在 bean 的 id 之 前 要 有 连 字符 (&) © 
所 以 对 于 一 个 给 定 id 为 myBean 的 FactoryBean ， 调用 容器 的 

Lat pe ANUS ce Aare FactoryBean 产品 ; 而 调用 “getBean("&myBean") 
方法 则 返回 FactoryBean 实例 本 身 。 


4.9 基于 注解 的 容器 配置 


配置 Spring 时 ， 注 解 要 比 XML 更 好 吗 ? 基于 注解 配置 的 介绍 就 提出 了 这 样 的 问题 ， 
这 种 方法 要 比 XML' 更 好 ' 吗 ? 简短 的 回答 就 是 具体 问题 具体 分 析 。 完 整 的 答案 就 是 
每 种 方法 都 有 它 的 利 与 兽 ， 通 常 是 让 开发 人 员 来 决定 使 用 哪 种 策略 更 适合 使 用 。 由 
于 定义 它们 的 方式 ， 注 解 在 它们 的 声明 中 提供 了 大 量 的 上 下 文 ， 使 得 配置 更 加 简短 
和 简洁 。 然 而 ，XML 更 擅长 装配 组 件 ， 而 不 需要 触 碰 它 们 源 代码 或 重新 编译 。 一 些 
开发 人 员 更 喜欢 装配 源码 而 其 他 人 认为 被 注解 的 类 不 再 是 POJO 了 ， 此外， 配置 变 
得 分 散 并 且 难 以 控制 。 


无 论 怎么 去 线 则 ， : Spring 都 可 以 容纳 两 种 方式 ， 甚 至 是 它们 的 混合 体 。 最 值得 指出 
的 是 通过 JavaConfig (4.127 ) 选择 ，Spring 允 许 以 非 侵入 式 的 方式 来 使 用 注解 ， 
而 不 需 要 触 碰 目 标 组 件 的 源 代 码 和 工具 ， 所 有 的 配置 方式 都 是 SpringSource Tool 
Suite 所 支持 的 。 


作为 XML 配置 的 另外 一 种 选择 ， 依靠 字 节 码 元 数据 的 基于 注解 的 配置 来 装配 组 件 
代替 了 伙 括 号 式 的 声明 。 作 为 使 用 XML 来 表述 bean 装配 的 替换 ， 开 发 人 员 可 以 
将 配置 信息 移入 到 组 件 类 本 身 中 ， 在 相关 的 类 ， 方 法 或 字段 声明 上 使 用 注解 。 正 如 
在 4.8.1.2 节 ，“ 示 例 : RequiredAnnotationBeanPostProcessor 所 提 到 的 ， 使 用 
BeanPostProcessor 来 连接 注解 是 扩展 Spring loC 容器 的 一 种 常用 方式 。 比 如 ， 
Spring 2.0 引入 的 使 用 @Required (4.9.1 节 ) 注解 来 强制 所 需 属性 的 可 能 性 。 在 
Spring 2.5 中 ， 可 以 使 用 相同 的 处 理 方法 来 驱 动 Spring 的 依赖 注入 。 从 本 质 上 来 
说 ，@Autowired 注解 提供 了 在 4.4.5 T ，" 自 动 装配 协 作者 ”中 描述 的 相同 能 力 ， 
但 却 有 更 细 粒 度 的 控制 和 更 广泛 的 适用 性 。Spring 2.5 也 添加 了 对 JSR-250 注解 
的 支持 ， 比 如 @Resource，@PostConstruct 和 @PreDestroy。Spring 3.0 添加 了 
对 JSR-330 (对 Java 的 依赖 注入 ) 注解 的 支持 ， 包 含 在 javax.inject 包 下 ， 比 如 
@Inject > @Qualifier > @Named 和 @Provider ， 当 JSR330 的 jar 包 在 类 路 径 下 时 
就 可 以 使 用 。 使 用 这 些 注 解 也 需要 在 Spring 容器 中 注册 特定 的 
BeanPostProcessor ° 


注意 


注解 注入 会 在 XML 注入 之 前 执行 ， 因 此 通过 两 种 方式 ， 那 么 后 面 的 配置 会 履 
盖 前 面 装 配 的 属性 


一 如 人 往常， 你 可 以 注册 它们 作为 独立 的 bean， 但 是 它们 也 可 以 通过 包含 下 面 的 基 
于 XML 的 Spring 配置 代码 片段 被 隐 式 地 注册 (注意 要 包含 context 命名 空间 ) 


<?xml version="1.0" encoding="UTF-8"?> 

<beans xmlns="http://www.springframework.org/schema/beans" xmins 
>xsi="http://www.w3.org/2001/XMLSchema -instance" xmlns:context= 
"http://www. springframework.org/schema/context" xsi:schemaLocati 
on="http://www.springframework.org/schema/bean[s http://www.spri 
ngframework.org/schema/beans/spring -beans-3.0.xsd http://ww.sp 
ringframework.org/schema/context http://www.springframework.org/ 
schema/context/spring-context-3.0.xsd"> 

<context :annotation-config/> 
</beans> 


( 隐 式 注册 的 后 处 理 器 & & AutowiredAnnotationBeanPostProcessor ， 
CommonAnnotationBeanPostProcessor ， 
PersistenceAnnotationBeanPostProcessor > VA A Ł ik ay 
RequiredAnnotationBeanPostProcessor ) 


my 
¢ alt 


<context:annotation-config/> 仅仅 查找 定义 在 同一 上 下 文中 的 bean 的 
注解 。 这 就 意味 着 ， 如 果 你 为 DispatcherServlet 
将 <context:annotation-config/> 放 置 在 WebApplicationContext P > a 
么 它 仅 仅 检 查 控制 器 中 的 @Autowired bean， 而 不 是 你 的 服务 层 bean， 可 以 
参看 16.2 节 ，“DispatcherServlet" 来 查看 更 多 信息 。 


4.9.1 @Required 


@Required 注解 应 用 于 bean 属性 的 setter 方法 ， 就 向 下 面 这 个 示例 : 


public class SimpleMovieLister { 
private MovieFinder movieFinder; 
@Required 
public void setMovieFinder(MovieFinder movieFinder) { 
this.movieFinder = movieFinder; 
} 


OA 


这 个 注解 只 是 表明 受 影 响 的 bean 的 属性 必须 在 bean 的 定义 中 或 者 是 自动 装配 中 
通过 明确 的 属性 值 在 配置 时 来 填充 。 如 果 受 影响 的 bean BRA RIAA MAR 
器 就 会 抛 出 异 常 ; 这 就 允许 了 急切 而 且 明 确 的 失败 ， 要 避免 
NullPointerException。 我 们 推荐 你 放 置 断言 到 bean 的 类 中 ， 上 比如 ， 放 置 到 初始 化 
方法 中 。 当 你 在 容器 外 部 使 用 类 时 ， 这 么 来 做 是 强制 那些 所 需 的 引用 和 值 。 


4.9.2 @Autowired 和 @lInject 


正如 预期 的 那样 ， 你 可 以 使 用 @Autowired 注解 到 "传统 的 "Setter FAP: 注意 在 
下 面 的 示例 中 ，JSR330 的 @Inject 注解 可 以 用 于 代替 Spring 的 @Autowired。 没 
有 必须 的 属性 ， 不 像 Spring 的 @Autowired 注解 那样 ， 如 果 要 注入 的 值 是 可 选 的 
话 ， 要 有 一 个 required 属性 来 表示 。 如 果 你 将 JSR330 的 JAR 包 放 置 到 类 路 径 
的 话 ， 这 种 行为 就 会 自 动 开启 。 


public class SimpleMovieLister { 
private MovieFinder movieFinder; 
@Autowired 
public void setMovieFinder(MovieFinder movieFinder) { 
this.movieFinder = movieFinder; 
} 


VURE 


你 也 可 以 将 注解 应 用 于 任意 名 称 和 /或 多 个 参数 的 方法 : 


public class MovieRecommender { 
private MovieCatalog movieCatalog; 
private CustomerPreferenceDao customerPreferenceDao; 
@Autowired 
public void prepare(MovieCatalog movieCatalog, CustomerPrefe 
renceDao customerPreferenceDao) { 
this.movieCatalog = movieCatalog; 
this.customerPreferenceDao = customerPreferenceDao; 


你 也 可 以 将 用 于 构造 方法 和 字段 : 


public class MovieRecommender { 

@Autowired 

private MovieCatalog movieCatalog; 

private CustomerPreferenceDao customerPreferenceDao; 

@Autowired 

public MovieRecommender(CustomerPreferenceDao customerPrefer 
enceDao) { 

this.customerPreferenceDao = customerPreferenceDao; 
} 
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也 可 以 提供 ApplicationContext 中 特定 类 型 的 所 有 bean， 通 过 添加 注解 到 期 望 哪 
种 类 型 的 数组 的 字段 或 者 方法 上 : 


public class MovieRecommender { 
@Autowired 
private MovieCatalog[] movieCatalogs; 
ei eine see 


相同 地 ， 也 可 以 用 于 特定 类 型 的 集合 : 


public class MovieRecommender { 
private Set<MovieCatalog> movieCatalogs; 
@Autowired 
public void setMovieCatalogs(Set<MovieCatalog> movieCatalogs 


Ds 


this.movieCatalogs = movieCatalogs; 


甚至 特定 类 型 的 Map 也 可 以 自动 装配 ， 但 是 期 望 的 键 的 类 型 是 String 4 ° Map 值 
会 包含 所 有 期 望 类 型 的 bean ， 而 键 会 包含 对 应 bean 的 名 字 : 


public class MovieRecommender { 
private Map<String, MovieCatalog> movieCatalogs; 
@Autowired 
public void setMovieCatalogs(Map<String, MovieCatalog> movie 
Catalogs) { 
this.movieCatalogs = movieCatalogs; 
} 


P aoi 
} 


默认 情况 下 ， 当 出 现 零 个 候选 bean 的 时 候 ， 自 动 装配 就 会 失败 ; 默认 的 行为 是 将 
被 注解 的 方法 ， 构 造 方法 和 字段 作为 需要 的 依赖 关系 。 这 种 行为 也 可 以 通过 下 面 这 
样 的 做 法 来 改变 。 


public class SimpleMovieLister { 
private MovieFinder movieFinder; 
@Autowired(required=false) 
public void setMovieFinder(MovieFinder movieFinder) { 
this.movieFinder = movieFinder; 
} 


OA 


i 
注意 
每 一 个 类 中 仅 有 一 个 被 注解 方法 可 以 标记 为 必须 的 ， 但 是 多 个 非 必 须 的 构造 方 
法 可 以 被 注解 。 在 那 种 情况 下 ， 每 个 构造 方法 都 要 考虑 到 而 且 Spring 使 用 依 
赖 可 以 被 满足 的 那个 构造 方法 ， 那 就 是 参数 最 多 的 那个 构造 方法 。 


@Autowired 需要 的 属性 推荐 使 用 @Required 注解 。 所 需 的 表示 了 属性 对 于 自动 装 
配 目的 不 是 必须 的 ， 如 果 它 不 能 被 自动 装配 ， 那 么 属性 就 会 忽略 了 。 另 一 方面 ， 


@Required 更 健壮 一 些 ， 它 强制 了 由 容器 支持 的 各 种 方式 的 属性 设置 。 如 果 没 有 注 
入 任何 值 ， 就 会 抛 出 对 应 的 异常 。 你 也 可 以 针对 我 们 熟知 的 解决 依赖 关系 的 接口 来 
使 用 @Autowired : BeanFactory，ApplicationContext ，Environment ， 
ResourceLoader ，ApplicationEventPublisher 和 MessageSource ° 2% %44 0 fe È 
们 的 扩展 接口 ， 比 如 ConfigurableApplicationContext 或 
ResourcePatternResolver 也 会 被 自动 解析 ， 而 不 需要 特殊 设置 的 必要 。 


public class MovieRecommender { 
@Autowired 
private ApplicationContext context; 
public MovieRecommender() { 


} 
A 


@Autowired > @Inject > @Resource 和 @Value 注解 是 由 Spring 的 
BeanPostProcessor 实现 类 来 控制 的 ， 反 过 来 告诉 你 你 不 能 在 
BeanPostProcessor 或 BeanFactoryPostProcessor X 类 型 (任意 之 一 ) 应 用 这 
些 注解 。 这 些 类 型 必须 明确 地 通过 XML 或 使 用 Spring 的 @Bean 方法 来 装 
Bi’ © 


4.9.3 使 用 限定 符 来 微调 基于 注解 的 自动 装配 


因为 通过 类 型 的 自动 装配 可 能 导致 多 个 候选 者 ， 那 么 在 选择 过 程 中 通常 是 需要 更 多 
的 控制 的 。 达 成 这 个 目的 的 一 种 做 法 就 是 Spring 的 @Qualifier 注解 。 你 可 以 用 特 
定 的 参数 来 关联 限定 符 的 值 ， 缩 小 类 型 的 see as > 那么 特定 的 bean 就 为 每 一 个 
参数 来 选择 。 最 简单 的 情形 ， 这 可 以 是 普通 描述 性 的 值 : 


i) 

JSR 330 的 @Qualifier 注解 仅仅 能 作为 元 注解 来 用 ， 而 不 像 Spring 的 
@Qualifier 可 以 使 用 字符 串 属 性 来 在 多 个 注入 的 候选 者 之 间 区 别 ， 并 可 以 放 在 
注解 ， 类 型 ， 字 段 ， 方 法 ， 构 造 方 法 和 参数 中 。 


public class MovieRecommender { 
@Autowired 
@Qualifier("main" ) 
private MovieCatalog movieCatalog; 


M aina 


@Qualifier 注解 也 可 以 在 独立 构造 方法 参数 或 方法 参数 中 来 指定 : 


public class MovieRecommender { 
private MovieCatalog movieCatalog; 
private CustomerPreferenceDao customerPreferenceDao; 


@Autowired 
public void prepare(@Qualifier("main") MovieCatalog movieCat 


alog, CustomerPreferenceDao customerPreferenceDao) { 


this.movieCatalog = movieCatalog; 
this.customerPreferenceDao = customerPreferenceDao; 


对 应 的 bean 的 定义 可 以 按 如 下 所 示 。 限 定 
的 构造 方法 参数 来 装配 。 


符 值 是 “main” 的 bean 会 用 限定 了 相同 值 


<?xml version="1.0" encoding="UTF-8"?> 
<beans xmlns="http://www.springframework.org/schema/beans" xmins 
>xsi="http://www.w3.org/2001/XMLSchema -instance" xmlns:context= 
"http://www. springframework.org/schema/context" xsi:schemaLocati 
on="http://www.springframework.org/schema/beans http://www. sprin 
gframework.org/schema/beans/spring -beans-3.0.xsd http://www.spr 
ingframework.org/schema/contex)t http://www.springframework.org/ 
schema/context/spring-context-3.0.xsd"> 
<context :annotation-config/> 
<bean class="example.SimpleMovieCatalog"> 
<qualifier value="main"/> 
<!-- 注入 这 个 bean 需 要 的 任何 依赖 --> 
</bean> 
<bean class="example.SimpleMovieCatalog"> 
<qualifier value="action"/> 
<!-- 注入 这 个 bean 需 要 的 任何 依赖 --> 
</bean> 
<bean id="movieRecommender" class="example.MovieRecommender" 
/> 
</beans> 


对 于 后 备 匹配 ，bean 名 称 被 认为 是 默认 的 限定 符 值 。 因 此 你 可 以 使 用 id 

为 “main”" 来 定义 bean， 来 蔡 代 瞬 套 的 限定 符 元 素 ， 这 也 会 达到 相同 的 匹配 结果 。 
然而 ， 尽 管 你 使 用 这 种 规约 来 通过 名 称 参照 特定 的 bean，@Autowired 从 根本 上 
来 说 就 是 关于 类 型 驱动 注入 和 可 选 语 义 限 定 符 的 。 这 就 是 说 限定 符 的 值 ， 即 便 有 
bean 的 名 称 作 为 后 备 ， 通 常 在 类 型 匹配 时 也 会 缩小 语义 ; 它们 不 会 在 语义 上 表达 
对 唯一 bean 的 id 的 引用 。 好 的 限定 符 的 值 是 “main” 或 ‘EMEA” 或 “persistent*， 特 
定 组 件 的 表达 特性 是 和 bean 的 id 独立 的 ， 在 比如 前 面 示例 之 一 的 匿名 bean 的 情 
况 下 它 是 可 能 自动 被 创建 的 。 


限定 符 也 可 以 用 于 类 型 集合 ， 正 如 上 面 讨论 过 的 ， 比 如 Set<MovieCatalog> ° 
在 这 种 情况 下 ， 根 据 声明 的 限定 符 ， 所 有 匹配 的 bean 都 会 被 注入 到 集合 中 。 这 就 
说 明了 限定 符 不 必 是 唯一 的 ; 它们 只 是 构成 了 算 选 条 件 。 比 如 ， 你 可 以 使 用 相同 的 
限定 符 “action” 来 定 义 多 个 MovieCatalog bean ; 它们 全 部 都 会 通过 
@Qualifier("action") 注 解 注 入 到 Set<MovieCatalog> 中 。 


a, 
提示 


如 果 你 想 通过 名 称 来 表达 注解 驱动 注入 ， 主 要 是 不 使 用 @Autowired， 即 便 在 技 
术 上 来 说 能 够 通过 @Qualifier 值 指向 一 个 bean 的 名 称 。 相 有 反 ， 使 用 JSR-250 
的 @Resource 注解 ， 在 语义 上 定义 了 通过 它 的 唯一 名 称 去 确定 一 个 具体 的 
标 组 件 ， 声 明 的 类 型 和 匹配 过 程 无 关 。 


由 于 这 种 语义 区 别 的 特定 后 果 ，bean 本 身 被 定义 为 集合 或 map 类 型 ， 是 不 能 通过 
@Autowired 来 进行 注入 的 ， 因 为 类 型 匹配 用 于 它们 不 太 人 合适。 对 于 这 样 的 bean 
使 用 @Resource， 通 过 唯一 的 名 称 指向 特定 的 集合 或 map 类 型 的 bean 。 


@Autowired 可 以 用 于 字段 ， 构 造 方法 和 多 参数 方法 ， 在 参数 级 允许 通过 限定 符 注 
解 缩小 。 相 比 之 下 ，@Resource 仅 支持 字段 和 仅 有 一 个 参数 的 bean 属性 的 
setter 方法 。 因 此 ， 如 果 你 的 注入 目标 是 构造 方法 或 多 参数 的 方法 ， 那 么 就 坚持 使 
用 限定 符 。 你 可 以 创建 你 自 定 义 的 限定 符 注 解 。 只 需 定义 一 个 注解 并 在 你 的 定义 中 
提供 @Qualifier 注解 即 可 。 注意 你 可 以 以 下 面 描述 的 方式 来 使 用 JSR 330 的 
@Qualifier 注解 ， 用 于 替换 Spring 的 @Qualifier 注解 。 如 果 在 类 路 径 中 有 ISR 
330 的 jar 包 ， 那 么 这 种 行为 是 自动 开启 的 。 


@Target({ElementType.FIELD, ElementType.PARAMETER} ) 
@Retention(RetentionPolicy.RUNTIME ) 

@Qualifier 

public @interface Genre { String value(); } 


之 后 你 可 以 在 自动 装配 的 字段 和 参数 上 提供 自 定 义 的 限定 符 : 


public class MovieRecommender { 
@Autowired 
@Genre("Action") 
private MovieCatalog actionCatalog; 
private MovieCatalog comedyCatalog; 
@Autowired 


public void setComedyCatalog(@Genre("Comedy") MovieCatalog c 
omedyCatalog) { 


this.comedyCatalog = comedyCatalog; 
} 


AL 


之 后 ， 为 候选 bean 提供 信息 ， 你 可 以 添加 <qualifier/> 标签 来 作 

为 <bean/> 标签 的 子 元 素 ， 然 后 指定 type 和 value 值 来 匹配 你 自 定义 的 限定 符 
注解 。 这 种 类 型 匹配 是 基于 注解 类 的 完全 限定 名 。 否 则 ， 作 为 一 种 简便 的 形式 ， 如 
果 没 有 名 称 冲 突 存 在 的 风险 ， 你 可 以 使 用 短 类 名 。 这 两 种 方法 都 会 在 下 面 的 示例 中 


<?xml version="1.0" encoding="UTF-8"?> 
<beans xmlns="http://www.springframework.org/schema/beans" xmins 
>XxS1i="http://www.w3.org/2001/XMLSchema -instance" xmlns:context= 
"http://www. springframework.org/schema/context" xsi:schemaLocati 
on="http://www.springframework.org/schema/beans http://www. sprin 
gframework.org/schema/beans/spring -beans-3.0.xsd 
http://www. springframework.org/schema/context http://www. springf 
ramework.org/schema/context/spring-context-3.0.xsd"> 
<context :annotation-config/> 
<bean class="example.SimpleMovieCatalog"> 
<qualifier type="Genre" value="Action"/> 
<!— 注入 这 个 bean 所 需要 的 任何 依赖 --> 
</bean> 
<bean class="example.SimpleMovieCatalog"> 
<qualifier type="example.Genre" value="Comedy"/> 
<!— 注入 这 个 bean 所 需要 的 任何 依赖 --> 
</bean> 
<bean id="movieRecommender" class="example.MovieRecommender" 
/> 
</beans> 


在 4.10 节 ，“ 类 路 径 扫 描 和 管理 的 组 件 " 中 ， 你 会 看 到 基于 注解 的 替代 ， 在 XML 中 
来 提供 限定 符 元 数据 。 特 别 是 在 4.10.7 节 ，“ 使 用 注解 提供 限定 符 元 数据 "中 。 


在 一 些 示 例 中 ， 使 用 无 值 的 注解 就 足够 了 。 这 当 注 解 服务 于 多 个 通用 目的 时 是 很 有 
用 的 ， 


而 且 也 可 以 用 于 集中 不 同类 型 的 依赖 关系 。 比 如 ， 当 没有 因特网 连接 时 ， 你 可 以 提 
供 脱 机 目 录 来 由 于 搜索 。 首 先 定义 简单 的 注解 : 


@Target({ElementType.FIELD, ElementType.PARAMETER} ) 
@Retention(RetentionPolicy.RUNTIME ) 

@Qualifier 

public @interface Offline { 


} 


之 后 将 注解 添加 到 要 被 自动 装配 的 字段 或 属性 上 : 


public class MovieRecommender { 
@Autowired 
@Offline 
private MovieCatalog offlineCatalog; 
AAA 


现在 来 定义 bean 的 限定 符 的 type : 


<bean class="example.SimpleMovieCatalog"> 
<qualifier type="0ffline"/> 

<!— 注入 这 个 bean 所 需要 的 任何 依赖 --> 

</bean> 


你 也 可 以 定义 自 定 义 的 限定 符 注 解 来 接受 命名 属性 ， 除 了 或 替代 简单 的 value & 
性 。 如果 多 个 属性 值 之 后 在 要 不 自动 装配 的 字段 或 参数 上 来 指定 ， 那 么 要 考虑 
bean 的 定义 必须 匹配 自动 装备 候选 者 的 所 有 属性 值 。 示 例 ， 考 虑 下 面 的 注解 定 


@Target({ElementType.FIELD, ElementType.PARAMETER} ) 
@Retention(RetentionPolicy.RUNTIME ) 

@Qualifier 

public @interface MovieQualifier { String genre(); 
Format format(); 


} 


AIP > Format 是 枚 举 类 型 : 


public enum Format { VHS, DVD, BLURAY } 


BS HS 


自动 装配 的 字段 使 用 自 定 义 的 限定 符 和 包含 genre 和 format 两 个 属性 的 值 来 注 


public class MovieRecommender { 
@Autowired 
@MovieQualifier(format=Format.VHS, genre="Action") 
private MovieCatalog actionvhsCatalog; 
@Autowired 
@MovieQualifier(format=Format.VHS, genre="Comedy" ) 
private MovieCatalog comedyvVhsCatalog; 
@Autowired 
@MovieQualifier(format=Format.DVD, genre="Action" ) 
private MovieCatalog actionDvdCatalog; 
@Autowired 
@MovieQualifier(format=Format.BLURAY, genre="Comedy" ) 
private MovieCatalog comedyBluRayCatalog; 
et pre 


最 后 ，bean 的 定义 应 该 包含 匹配 的 限定 符 值 。 这 个 示例 也 展示 了 bean 的 元 属性 可 
能 用 于 替代 <qualifier/> 子 元 素 。 如 果 可 用 ， <qualifier/> 和 它 的 属性 优 
先 ， 但 是 如 果 目 前 没有 限定 符 ， 自 动 装配 机 制 就 会 在 <meta/> 标签 提供 的 值 上 失 
效 ， 就 像 下 面 这 个 示例 中 的 最 后 两 个 bean。 


<?xml version="1.0" encoding="UTF-8"?> 
<beans xmlns="http://www.springframework.org/schema/beans" xmins 
:xsi="http://www.w3.org/2001/XMLSchema -instance" xmlns:context= 
"http://www. springframework.org/schema/context" xsi:schemaLocati 
on="http://www.springframework.org/schema/beans http://www. sprin 
gframework.org/schema/beans/spring -beans-3.0.xsd http://www. spr 
ingframework.org/schema/context http://www.springframework.org/s 
chema/context/spring-context-3.0.xsd"> 
<context :annotation-config/> 
<bean class="example.SimpleMovieCatalog"> 
<qualifier type="MovieQualifier"> 
<attribute key="format" value="VHS"/> 
<attribute key="genre" value="Action"/> 
</qualifier> 
<!— 注入 这 个 bean 所 需要 的 任何 依赖 --> 
</bean> 
<bean class="example.SimpleMovieCatalog"> 
<qualifier type="MovieQualifier"> 
<attribute key="format" value="VHS"/> 
<attribute key="genre" value="Comedy"/> 
</qualifier> 
<!— 注入 这 个 bean 所 需要 的 任何 依赖 --> 
</bean> 
<bean class="example.SimpleMovieCatalog"> 
<meta key="format" value="DVD"/> 
<meta key="genre" value="Action"/> 
<!— 注入 这 个 bean 所 需要 的 任何 依赖 --> 
</bean> 
<bean class="example.SimpleMovieCatalog"> 
<meta key="format" value="BLURAY"/> 
<meta key="genre" value="Comedy"/> 
<!— 注入 这 个 bean 所 需要 的 任何 依赖 --> 
</bean> 
</beans> 


4.9.4 CustomAutowireConfigurer 


CustomAutowireConfigurer 是 BeanFactoryPostProcessor 的 一 种 ， 它 使 得 你 可 以 
注册 你 自己 定义 的 限定 符 注解 类 型 ， 即 便 它 们 没有 使 用 Spring 的 @Qualifier 注解 
也 是 可 以 的 。 


<bean id="customAutowireConfigurer" class="org.springframework.b 
eans.factory.annotation.CustomAu 
towireConfigurer"> 
<property name="CustomQualifierTypes"> 
<set> 
<value>example.CustomQualifier</value> 
</set> 
</property> 
</bean> 


AutowireCandidateResolver 的 特别 实现 类 对 基于 Java 版 本 的 应 用 程序 上 下 文 激 
活 。 在 Java 5 之 前 的 版 本 中 ， 限 定 符 注 解 是 不 支持 的 ， 因 此 自动 装配 候选 者 仅 由 
每 个 bean 定义 中 的 autowire-candidate 值 来 决定 ， 还 有 在 <beans/> 元 素 中 的 
任何 可 用 的 default-autowire-candidates 模式 也 是 可 以 的 。 在 Java5 之 后 的 
版 本 中 ，@Qualifier 注解 的 存在 还 有 任意 使 用 CustomAutowireConfigurer 注册 
的 自 定义 注解 也 将 发 挥 作 用 。 


不 管 Java 的 版 本 ， 当 多 个 bean 作为 自动 装配 的 候选 者 ， 决 定 “ 主 要 ”候选 者 的 方式 
也 th 同 的 : 如 果 候 选 者 中 一 个 bean 的 定义 有 primary B 性 精确 地 设置 为 true ， 
那么 它 就 会 被 选择 。 


4.9.5 @Resource 


Spring 也 支持 使 用 ISR 250 49 @Resource 注解 在 字段 或 bean 属性 的 setter 方法 
上 的 注 入。 这 在 Java EE 5 和 6 中 是 一 个 通用 的 模式 ， 比 如 在 JSF 1.2 中 管理 的 
bean 或 JAX-WS 2.0 端点 。Spring 也 为 其 所 管理 的 对 象 支持 这 种 模式 。 


@Resource 使 用 名 称 属 性 ， 默 认 情 况 下 Spring 解释 这 个 值 作为 要 注入 的 bean 的 
名 称 。 


AVIS TL > to Ri HG by-name 语义 ， 正 如 在 这 个 示例 所 展示 的 : 


public class SimpleMovieLister { 
private MovieFinder movieFinder; 
@Resource(name="myMovieFinder" ) 
public void setMovieFinder(MovieFinder movieFinder) { 
this.movieFinder = movieFinder; 


} 


p 果 没有 明确 地 指定 名 称 ， 那 么 默认 的 名 称 就 从 字段 名 称 或 setter 方法 中 派生 出 
来 。 以 字段 为 例 ， 它 会 选用 字段 名 称 ; 以 setter 方法 为 例 ， 它 会 选用 bean 的 属性 
名 称 。 所 以 下 面 的 示例 中 有 名 为 “movieFinder 的 bean 通过 setter 方法 来 注入 : 


public class SimpleMovieLister { 
private MovieFinder movieFinder; 
@Resource 
public void setMovieFinder(MovieFinder movieFinder) { 
this.movieFinder = movieFinder; 
} 


i 
注意 


使 用 注解 提供 的 名 称 被 感知 CommonAnnotationBeanPostProcessor 的 
ApplicationContext 解析 成 bean 的 名 称 。 名 称 可 以 通过 INDI 方式 来 解析 ， 只 
要 你 明确 地 配置 了 Spring 的 SimpleJndiBeanFactory。 然 而 ， 还 是 推荐 你 基 
于 默认 行为 并 仅 使 用 Spring 的 JNDI 查找 能 力 来 保存 间接 的 水 平 。 


在 使 用 @Resource 并 没有 明确 指 定名 称 的 独占 情况 下 ， 和 @Autowired 相似 ， 
@Resource 发 现 主要 类 型 匹配 ， 而 不 是 特定 名 称 bean 并 解析 了 诸 知 的 可 解析 的 依 
赖 关系 : BeanFactory > ApplicationContext > ResourceLoader ， 
ApplicationEventPublisher > MessageSource 和 接口 。 


此 ， 在 下 面 的 示例 中 > customerPreferenceDao 字段 首先 寻找 名 为 
customerPreferenceDao 的 bean， 之 后 回 到 匹配 CustomerPreferenceDao 的 主 类 
型 。“context" 字 段 基于 已 知 的 可 解析 的 依赖 类 型 ApplicationContext 注入 。 


public class MovieRecommender { 
@Resource 
private CustomerPreferenceDao customerPreferenceDao; 
@Resource 
private ApplicationContext context; 
public MovieRecommender() { 


} 
M ee 


4.9.6 @PostConstruct 和 @PreDestroy 


CommonAnnotationBeanPostProcessor 不 但 能 识别 别 @Resource 注解 ， 而 且 还 能 
识别 JSR-250 生命 周期 注解 。 在 Spring 2.5 中 引入 ， 对 这 些 注 解 的 支持 提供 了 在 
初始 化 回调 (4611F 节 ) 和 销毁 回调 (4.6.1.2 节 ) 中 的 另 一 种 选择 。 
只 要 CommonAnnotationBeanPostProcessor 在 Spring 的 ApplicationContext 中 
注册 ， 一 个 携带 这 些 注解 之 一 的 方法 就 同时 被 调用 了 ， 和 Spring 生命 周期 接口 方 
i& 3 a 明 回 调 方法 相对 应 。 在 下 面 的 示例 中 ， 在 初始 化 后 缓存 会 预先 填充 ， 
在 销毁 后 会 A 青 理 。 


public class CachingMovieLister { 
@PostConstruct 
public void populateMovieCache() { 
// 在 初始 化 时 填充 movie cache... 
} 


@PreDestroy 

public void clearMovieCache() { 
// 在 销毁 后 清理 movie cache... 

} 


关于 组 合 多 个 生命 周期 机 制 影响 的 细节 内 容 ， 请 参考 4.6.1.4 节 ，“ 组 合生 命 周 
期 机 制 ”。 


4.10 类 路 径 扫 描 和 管理 的 组 件 


本 章 中 的 大 多 数 示例 都 使 用 了 XML 来 指定 配置 元 数据 在 Spring 的 容器 中 生产 每 一 
个 BeanDefinition 。 之 前 的 章节 (4.9 节 ，"“ 基 于 注解 的 容器 配置 ") 表述 了 如 何 通过 
代码 级 的 注解 来 提供 大 量 的 配置 信息 。 尽 管 在 那些 示例 中 ，“ 基 础 的 "bean 的 定义 

都 是 在 XML 文 件 中 来 明确 定义 的 ， 而 注解 仅仅 进行 依赖 注入 。 本 节 来 说 明 另 外 一 
种 通过 扫描 类 路 径 的 方式 来 隐 式 检测 候选 组 件 。 候 选 组件 是 匹配 过 滤 条 件 的 类 库 ， 
并 有 在 容器 中 注册 的 对 应 的 bean 的 定义 。 这 就 可 以 不 用 XML 来 执行 bean 的 注 
MY ， 那 么 你 就 可 以 使 用 注解 (比如 @Component) > Aspect) 风格 的 表达 式 ， 
或 者 是 你 子 定义 的 过 滤 条 件 来 选择 那些 类 会 有 在 容 器 中 注册 的 bean。 


į 
EE 


从 Spring 3.0 开始 ， 很 多 由 Spring JavaConfig 项 目 提供 的 特性 作为 Spring 
Framework 核心 的 一 部 分 了 。 这 就 允许 你 使 用 Java 而 不 是 传统 的 XML 文件 
来 定义 bean 了 。 看 一 看 @Configuration > @Bean > @lImport 和 
@DependsOn 注解 的 例子 来 使 用 它们 的 新 特性 。 


4.10.1 @Component 和 更 多 典型 注解 


在 Spring 2.0 版 之 后 ，@Repository 注解 是 任意 满足 它 的 角色 或 典型 (上 比如 熟知 的 
数 据 访 问 对 象 ，DAO ) 库 的 类 的 标记 。 在 这 个 标记 的 使 用 中 ， 就 是 在 14.2.2 
节 ，“ 表 达 式 翻译 ”中 描述 的 表达 式 自动 翻译 。 


Spring2.5 引 入 了 更 多 的 注解 : @Component ，@Service 和 @Controller 


@Component 是 对 Spring 任意 管理 组 件 的 通用 刻 板 。@Repository ，@Service 
和 @Controller 是 对 更 多 的 特定 用 例 @Component 的 专业 化 ， 比 如 ， 在 持久 层 ， 服 
务 层 和 表现 层 。 因 此 ， 你 可 以 使 用 @Component 注解 你 的 组 件 类 ， 但 是 使 用 
@Repository > @Service X@Controller 注解 来 替代 的 话 ， 那 么 你 的 类 更 合适 由 工 
具 来 处 理 或 和 不 同 的 方面 相关 联 。 上 比如， 这些 刻 板 注 解 使 得 理想 化 的 目标 称 为 切入 
点 。 而 且 @Repository > @Service 和 @Controller 也 可 以 在 将 来 Spring 
Framework 的 发 布 中 携带 更 多 的 语义 。 因 此 ， 如 果 对 于 服务 层 ， 你 在 
@Component 或 @Service 中 间 选 择 的 话 ， 那 么 @Service 无 疑 是 更 好 的 选择 。 相 
似 地 ， 正 如 上 面 提 到 的 ， 在 持久 层 中 ，@Repository 已 经 作为 自动 异 常 翻译 的 表示 
所 被 支持 


4.10.2 自动 检测 类 和 bean 的 注册 


Spring 可 以 自动 检测 刻板 类 并 在 ApplicationContext 中 注册 对 应 的 
BeanDefinition。 比 如 ， 下 面 的 两 个 类 就 是 自动 检测 的 例子 : 


@Service 
public class SimpleMovieLister { 
private MovieFinder movieFinder; 
@Autowired 
public SimpleMovieLister(MovieFinder movieFinder) { 
this.movieFinder = movieFinder; 
} 
} 


@Repository 
public class JpaMovieFinder implements MovieFinder { 
// 为 了 清晰 省 略 了 实现 


要 自动 检测 这 些 类 并 注册 对 应 的 bean， 你 需要 包含 如 下 的 XML 元 素 ， 其 
中 的 base-package 元 素 通常 是 这 两 个 类 的 的 父 包 。 (也 就 是 说 ， 你 可 以 指定 以 去 
号 分 隔 的 列表 来 为 每 个 类 引入 父 包 。 ) 


<?xml version="1.0" encoding="UTF-8"?> 

<beans xmlns="http://www.springframework.org/schema/beans" xmins 
>xsi="http://www.w3.org/2001/XMLSchema -instance" xmlns:context= 
"http://www. springframework.org/schema/context" xsi:schemaLocati 
on="http://www.springframework.org/schema/beans http://www.sprin 
gframework.org/schema/beans/spring -beans-3.0.xsd http://www. spr 
ingframework.org/schema/context http://www.springframework.org/s 
chema/context/spring-context-3.0.xsd"> 

<context:component-scan base-package="org.example"/> 

</beans> 


对 类 路 径 包 的 扫描 需要 存在 类 路 径 下 对 应 的 目录 。 当 你 使 用 Ant 来 构建 JAR 包 
时 ， 要 保证 你 没有 激活 JAR 目标 中 的 files-only 开关 。 


此 外 ， 当 你 使 用 component-scan (组 件 - 扫 描 ， 译 者 注 ) 时 ， 
AutowiredAnnotationBeanPostProcessor 和 
CommonAnnotationBeanPostProcessor 二 者 都 是 隐 式 包含 的 。 这 就 意味 着 两 个 组 
件 被 自动 检测 之 后 就 装配 在 一 起 了 -而 不 需要 在 XML 中 提供 其 它 任何 bean 的 配置 
元 数据 。 


i 
注意 
你 可 以 将 annotation-config 属性 置 为 false 来 关闭 


AutowiredAnnotationBeanPostProcessor 的 
CommonAnnotationBeanPostProcessor 注册 。 


4.10.3 使 用 过 滤器 来 自 定 义 扫 描 


默认 情况 下 ， 使 用 @Component，@Repository > @Service > @Controller 注解 或 
使 用 了 进行 自 定义 的 @Component 注解 的 类 本 身 仅仅 检测 候选 组 件 。 你 可 以 修改 
并 扩展 这 种 行为 ， 仅仅 应 用 自 定义 的 过 滤器 就 可 以 了 。 在 component- 
scan 元 素 中 添加 include-filter 或 exclude-filter TAR 就 可 以 了 。 每 个 过 滤器 元 素 
需要 type 和 expression 属性 。 下 面 的 表格 描述 了 过 滤 选 项 。 


表 4.5 过 过 tT HRS na 器 类 型 
滤器 类 型 REAR BI 描述 
wrote ie org.example.SomeAnnotation 在 目标 组 件 的 类 型 层 表 示 的 当 
i 分 > 展 / 字 现 

> (分 Be En 组 件 分 配 去 (扩展 /实现 ) 

aspectj org.example..*Servicet+ AspectJ 类 型 表达 式 来 匹配 目 
yu T 1 

eR) CE org.example.Default.* 正则 表达 式 来 匹配 目标 组 件 类 

custom ( 自 定 i 日 是 n 

L) org.example.MyTypeFilter org.springframework.core.tyf 

接口 的 实现 类 


下 面 的 示例 代码 展示 了 XML 配置 忽略 所 有 人 @Repository 注解 并 使 用 "sub" 库 来 替 
代 。 


<beans> 
<context:component-scan base-package="org.example"> 
<context:include-filter type="regex" expression=".*Stub.*Rep 
ository"/> 
<context:exclude-filter type="annotation" 
expression="org.springframework.stereotype.Repository 
Ws 
</context :component - scan> 
</beans> 


1 | 
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你 可 以 使 用 <component-scan/> 元 素 中 的 use-default-filter="false" 属 性 来 关 
闭 默 认 的 过 滤 器 。 这 会 导致 关闭 食用 @Component ，@Repository ， 
@Service 或 @Controller 注解 的 类 的 自动 检测 。 


4.10.4 使 用 组 件 定 义 bean 的 元 数据 


Spring 组 件 可 以 为 容器 提供 bean 定义 的 元 数据 。 你 可 以 使 用 用 于 定义 bean 元 数 
据 的 @Configuration 注解 的 类 的 @Bean 注解 。 这 里 有 一 个 示例 : 


@Component 
public class FactoryMethodComponent { 
@Bean @Qualifier ("public") 
public TestBean publicInstance() { 
return new TestBean("publicInstance"); 


public void dowork() { 
// 和 忽略 组 件 方法 的 实现 
} 


这 个 类 在 Spring 的 组 件 中 有 和 包含 在 它 的 doWork() 方 法 中 的 特定 应 用 代码 。 它 也 提 
供 了 bean 的 定义 并 且 有 工厂 方法 来 指向 publiclnstance() 方 法 。@Bean 注解 标识 
了 工厂 方法 和 其 它 bean 定义 的 属性 ， 比 如 通过 @Qualifier 注解 表示 的 限定 符 。 其 
它 方法 级 的 注 解 可 以 用 于 特定 的 是 @Scope ， @Lazy i 自 定 义 限 定 符 注解 。 自 动 

装配 字段 和 方法 也 是 支持 的 ， 这 在 之 前 讨论 过 ， 还 有 对 自动 装配 @Bean 方法 
的 支持 : 


@Component 
public class FactoryMethodComponent { 
private static int i; 
@Bean @Qualifier ("public") 
public TestBean publicInstance() { 
return new TestBean("publicInstance"); 


} 

// 使 用 自 定 义 标 识 符 并 自动 装配 方法 参数 

@Bean 

protected TestBean protectedInstance(@Qualifier( "public") T 
estBean spouse, @Value("#{privateInstance.age}") String country) 


{ 
TestBean tb = new TestBean("protectedInstance", 1); tb.s 
etSpouse(tb); 
tb.setCountry(country); 
return tb; 
} 
@Bean @Scope(BeanDefinition.SCOPE_SINGLETON) 
private TestBean privateInstance() { 
return new TestBean("privateInstance", i++); 
} 


@Bean @Scope(value = WebApplicationContext.SCOPE_SESSION, pr 
oxyMode = ScopedProxyMode.TARGET_CLASS) 
public TestBean requestScopedInstance() { 
return new TestBean("requestScopediInstance", 3); 
} 


这 个 示例 为 另外 一 个 名 为 privatelnstance 的 bean 的 Age 属性 自动 装配 了 String 
方法 参数 country ° Spring 的 表达 式 语 言 元 素 通过 #{<expression>} 表示 定义 了 
属性 的 值 。 对 于 @Value 注解 ， 当 解析 表达 式 文本 时 ， 表 达 式 解析 器 会 预先 配置 来 
查看 bean 的 名 称 。 


Spring 组 件 中 的 @Bean 方法 会 被 不 同方 式 来 处 理 ， 而 不 会 像 Spring 中 
@Configuration 的 类 那样 。 不 同 的 是 @Component 类 没有 使 用 CGLIB 来 加 强 并 拦 
截 字段 和 方法 的 调用 。CGLIB 代理 是 调用 @Configuration 类 和 创建 bean 元 数据 引 
用 协作 对 象 的 @Bean 方法 调用 的 手 段 。 方 法 没有 使 用 通常 的 Java 语义 来 调用 。 
相 比 之 下 ， 使 用 @Component 类 @Bean 方法 来 调用 方法 或 字段 有 标准 的 Java 语 
L o 


4.10.5 命名 自动 检测 组 件 


当 组 件 被 自动 检测 作为 扫描 进程 的 一 部 分 时 ， 它 的 bean 名 称 是 由 
BeanNameGenerator 策略 来 生成 并 告知 扫描 器 的 。 黑 认 情 况 下 ，Spring 的 刻板 注 
解 (@Component > @Repository > @Service 和 @Controller) 包含 name 值 从 而 
提供 对 应 bean 定义 的 名 称 。 注意 JSR 330 的 @Named 注解 可 以 被 用 于 检测 组 件 
和 为 它们 提供 名 称 的 手段 。 如 果 在 类 路 径 中 有 ISR 330 的 JAR 包 的 话 ， 这 种 行为 
会 被 自动 开启 。 


如 果 注 解 包含 name 值 或 者 对 于 其 它 任意 被 检测 的 组 件 (比如 那些 被 自 定义 过 滤器 
发 现 的 ) > RUKI bean 的 名 称 生成 器 返回 未 大 写 的 非 限定 符 类 名 。 比 如 ， 如 果 下 
面 的 两 个 组 件 被 检测 到 了 ， 那 么 名 称 可 能 是 myMovieLister 和 movieFinderlmpl : 


@Service("myMovieLister") 

public class SimpleMovieLister { 
| mee 

} 

@Repository 

public class MovieFinderImpl implements MovieFinder { 
AR 

} 


i 
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如 果 你 不 想 使 用 默认 的 bean 命名 策略 ， 你 可 以 提供 自 定 义 的 bean 命名 策 
略 。 首 先 ， 实 现 BeanNameGenerator 接口 ， 要 保证 包含 默认 的 没有 参数 的 构 


造 方法 。 之 后 ， 在 配置 扫描 器 时 ， 要 提供 类 的 完全 限定 名 。 


<beans> 

<context:component-scan base-package="org.example" name-gene 
rator="org.example.MyNameGenerator" /> 
</beans> 


作为 通用 的 规则 ， 要 考虑 使 用 注解 指定 名 称 时 ， 其 它 组 件 可 能 会 有 对 它 的 明确 的 引 
用 。 另 一 方面 ， 当 容器 负责 装配 时 ， 自 动 生 成 名 称 是 可 行 的 。 


4.10.6 为 自动 检测 组 件 提 供 范 围 


一 般 情况 下 ，Spring 管理 的 组 件 ， 自 动 检测 组 件 的 默认 和 最 多 使 用 的 范围 是 单 例 范 
。 然 而， 有 事 你 需要 其 它 范 围 ，Spring 2.5 提供 了 一 个 新 的 @Scope 注解 。 仅 仅 
使 用 注解 提供 范围 的 名 称 : 


@Scope("prototype" ) 

@Repository 

public class MovieFinderImpl implements MovieFinder { 
UE eae 


} 


i 


注意 
Sco 
配置 扫描 器 时 ， 要 提供 类 的 完全 限定 名 : 


<beans> 
<context:component-scan base-package="o0rg.example" scope-res 


olver="org.example.MyScopeResolver" /> 
</beans> 


当 使 用 特定 反而 非 单 例 范 围 时 ， 它 可 能 必须 要 为 有 范围 的 对 象 生 成 代理 。 这 个 原 
在 4.5.4.5 节 ，“ 各 种 范围 的 bean 作为 依赖 "中 描述 过 了 。 出 于 这 样 的 目的 ， 在 
component-scan 元 素 中 可 以 使 用 scoped-proxy 属性 。 三 种 可 能 的 值 是 : 

no (Æ) interface (接口 ) 和 targetClass (目标 类 ) 。 比 如 ， 下 面 的 配置 就 会 局 
动 标准 的 IDK 动态 代理 : 


<beans> 
<context:component-scan base-package="org.example" scoped-pr 


oxy="interfaces" /> 
</beans> 


4.10.7 使 用 注解 提供 限定 符 元 数据 


@Qualifier 注解 在 4.9.3 节 ，“ 使 用 限定 符 来 微调 基于 注解 的 自动 装配 "中 讨论 过 
Jo 那 部 分 中 的 示例 说 明了 @Qualifier 注解 的 使 用 和 当 你 需要 处 理 自动 装配 候选 者 
时 ， 自 定义 限定 符 注解 来 提供 微调 控制 。 因 为 那些 示例 是 基于 XML 的 bean 定义 
的 ， 限 定 符 元 数据 在 候选 者 bean 定义 中 提供 ， 并 使 用 了 XML 中 的 bean 元 素 的 


qualifier 和 meta 子 元 素 。 当 对 自动 检测 组 件 使 用 基于 类 路 径 扫 描 时 ， 你 可 以 在 候 
选 者 类 中 使 用 类 型 -级 的 注解 提供 限 定 符 元 数据 。 下 面 的 三 个 示例 就 展示 了 这 个 技 
术 : 


@Component 

@Qualifier ("Action") 

public class ActionMovieCatalog implements MovieCatalog { 
OA 


@Component 

@Genre("Action" ) 

public class ActionMovieCatalog implements MovieCatalog { 
Pf erica 

} 


@Component 

@Offline 

public class CachingMovieCatalog implements MovieCatalog { 
人 

} 


i J 


对 于 大 多 数 基于 注解 的 方式 ， 要 记得 注解 元 数据 会 绑 定 到 类 定义 本 身 中 去 ， 而 


使 用 XML 就 允许 对 多 个 相同 类 型 的 bean 在 它们 的 限定 符 元 数据 中 提供 变化 ， 
因为 那些 元 数据 是 对 于 每 个 实例 而 不 是 每 个 类 提供 的 。 


4.11 使 用 JSR 330 标准 注解 


从 Spring 3.0 开始 ，Spring 提供 了 对 JSR-330 标准 注解 (依赖 注入 ) 的 支持 。 这 
些 注解 可 以 和 Spring 注解 以 相同 方式 被 扫描 到 。 你 仅仅 需要 在 类 路 径 下 添加 相关 
的 jar 包 即 可 。 


ny 
A 
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如 果 你 使 用 Maven， 那 么 在 标准 Maven 人 仓库 
(http://repo1.maven.org/maven2/javax/inject/javax.inject/1/) 中 javax.inject 
的 artifact 是 可 用 的 。 你 仅仅 需要 在 pom.xml 中 添加 如 下 的 依赖 即 可 : 


<dependency> 
<groupId>javax.inject</groupId> 
<artifactId>javax.inject</artifactId> 
<version>1</version> 

</dependency> 


4.11.1 i A @Inject 和 @Named 进行 依赖 注入 
除了 @Autowired，javax.inject.Inject 还 可 以 是 下 面 这 样 : 


import javax.inject.Inject; 
public class SimpleMovieLister { 
private MovieFinder movieFinder; 
@Inject 
public void setMovieFinder(MovieFinder movieFinder) { 
this.movieFinder = movieFinder; 


} 
OA 


至 于 @Autowired， 可 以 在 类 级 别 ， 字 段 级 别 ， 方 法 级 别 和 构造 方法 参数 级 别 使 用 
@Inject。 如 果 你 想 对 应 该 被 注入 的 依赖 使 用 限定 符 名 称 ， 你 应 该 按 如 下 方式 使 用 
@Named 注 解 : 


import javax.inject.Inject; import javax.inject.Named; public cl 
ass SimpleMovieLister { 

private MovieFinder movieFinder; 

@Inject 

public void setMovieFinder (@Named("main") MovieFinder movieF 
inder) { 

this.movieFinder = movieFinder; 
} 


LP ea 


4.11.2 @Named : @Component 注解 的 标准 等 同 


除了 @Component，javax.inject.Named 还 可 以 是 下 面 这 样 : 


import javax.inject.Inject; 
import javax.inject.Named; 
@Named("movieListener" ) 
public class SimpleMovieLister { 
private MovieFinder movieFinder; 
@Inject 
public void setMovieFinder(MovieFinder movieFinder) { 
this.movieFinder = movieFinder; 


} 
E A o 


使 用 @Component 而 不 指定 组 件 的 名 称 是 很 常用 的 方式 。@Named 可 以 被 用 于 相 
同 的 情况 : 


import javax.inject.Inject; 
import javax.inject.Named; 
@Named 
public class SimpleMovieLister { 
private MovieFinder movieFinder; 
@Inject 
public void setMovieFinder(MovieFinder movieFinder) { 
this.movieFinder = movieFinder; 


} 
V 全 


当 使 用 @Named ， 当 使 用 Spring 注解 时 ， 可 以 以 相同 的 方式 使 用 组 件 扫描 : 


<beans> 
<context:component-scan base-package="org.example"/> 
</beans> 


4.11.3 标准 方法 的 限制 


当 使 用 标准 注解 时 ， 了 解 一 些 不 可 用 ， 但 是 很 重要 的 特性 是 必要 的 ， 在 下 面 的 表格 
中 给 出 : 


表 4.6 Spring 注解 和 标准 注解 的 对 比 


Spring javax.inject.* javax.inject 限制 /注释 
@Autowired @Inject @lnject 没有 'required' 属 性 
@Component @Named 


jsr-330 默认 范围 和 Spring 的 
prototype 相似 。 但 是 ， 要 保持 和 
Spring 一 般 默 认 值 一 致 ， 在 Spring 
容器 中 jsr-330 的 bean 声 明 默认 是 
singleton 的 。 要 使 用 另外 的 范围 ， 你 
应 该 使 用 Spring 的 @Scope 注解 。 
javax.inject 也 提供 @Scope 注解 。 不 
过 这 仅 仅 用 于 创建 你 自己 的 注解 。 


@Scope("singleton") @Singleton 


@Qualifier @Named 
@Value - 不 等 同 
@Required - 不 等 同 


@Lazy z 不 等 同 


4.12 基于 Java 的 容器 配置 


4.12.1 基本 概念 : @Configuration 和 @Bean 


Spring 中 新 的 Java 配置 支持 的 核心 ee 注解 的 类 。 这 些 类 主要 包 
括 @Bean 注解 的 方法 来 为 Spring 的 loC 容器 管理 的 对 象 定 义 实 例 ， 配 置 和 初始 
化 逻辑 。 


使 用 @Configuration 来 注解 类 表示 类 可 以 被 Spring 的 loC 容器 所 使 用 ， 作为 bean 
定义 的 资源 。 最 简单 的 @Configuration 类 可 以 是 这 样 的 : 


@Configuration 
public class AppConfig { 
@Bean 
public MyService myService() { 
return new MyServiceImpl(); 
} 


这 和 Spring 的 XML 文件 中 的 <beans/> 非常 类 似 ， 上 面 的 AppConfig 类 和 下 面 
的 代码 是 等 同 的 : 


<beans> 

<bean id="myService" class="com.acme.services.MyServiceImpl" 
/> 
</beans> 


正如 你 看 到 的 ，@Bean 注解 扮演 了 和 <bean/> 元 素 相同 的 角色 。@Bean 注解 会 
在 下 面 的 章节 中 详细 地 讨论 。 首 先 ， 我 们 要 来 看 看 使 用 基于 Java 的 配置 创建 
Spring 容器 的 各 种 方 式 。 


4.12.2 使 用 AnnotationConfigApplicationContext 实例 化 
Spring 容器 


下 面 的 章节 说 明了 Spring 的 AnnotationConfigApplicationContext， 在 Spring 3.0 
中 是 新 加 入 的 。 这 个 全 能 的 ApplicationContext 实现 类 可 以 接受 不 仅仅 
是 @Configuration 类 作为 输入 ， 也 可 以 是 普通 的 @Component 类 ， 还 有 使 用 
JSR-330 元 数 据 注 解 的 类 。 


当 @Configuration 类 作为 输入 时 ，@Configuration 类 本 身 作 为 bean 被 注册 了 ， 
并 且 类 内 所 有 声明 的 @Bean 方法 也 被 作为 bean 注册 了 。 


当 @Component 和 JSR-330 类 作为 输 AN > Ell 被 注册 为 bean， 并 HR 假 
设 如 @Autowired X@lnject 的 DI 元 数据 在 类 中 需要 的 地 方 使 用 。 


4.12.2.1 简单 构造 


当 实 例 化 ClassPathXmlApplicationContext 时 ， 以 大 致 相同 的 方式 ， 当 实例 化 
AnnotationConfigApplicationContext 时 ，@Configuration 类 可 能 被 作为 输入 。 这 
就 允许 在 Spring 容器 中 完全 可 以 不 使 用 XML : 


public static void main(String[] args) { 
ApplicationContext ctx 
= new AnnotationConfigApplicationContext(AppConfig. clas 
s); 
MyService myService = ctx.getBean(MyService.class); 
myService.doStuff(); 


正如 上 面 所 提 到 的 ，AnnotationConfigApplicationContext 不 仅仅 局 限于 和 
@Configuration 类 合作 。 任 意 @Component 或 JSR-330 注解 的 类 都 可 以 作为 构造 
方法 的 输入 。 比 如 : 


public static void main(String[] args) { 
ApplicationContext ctx = new 
AnnotationConfigApplicationContext(MyServiceImpl.class, 
Dependencyi.class, Dependency2.MyService myService = 
ctx.getBean(MyService.class); 
myService.doStuff(); 


上 面 假设 MyServicelmpl > Dependency 和 Dependency2 使 用 了 Spring 依赖 注 
入 注解 ， 比 如 @Autowired ° 


4.12.2.2 使 用 register(Class<?>...) 来 编程 构建 容器 


AnnotationConfigApplicationContext 可 以 使 用 无 参 构 造 方法 来 实例 化 ， 之 后 使 用 
register() 方法 来 配置 。 这 个 方法 当 编 程 构 建 
AnnotationConfigApplicationContext 时 尤其 有 用 。 


public static void main(String[] args) { 

AnnotationConfigApplicationContext ctx = new 
AnnotationConfigApplicationContext(); 

ctx.register(AppConfig.class, OtherConfig.class); 
ctx.register(AdditionalConfig.class); 
ctx.refresh(); 
MyService myService = ctx.getBean(MyService.class); 
myService.doStuff(); 


4.12.2.3 使 用 scan(String..) 开 后 组 件 扫描 


有 经 验 的 Spring 用 户 肯 定 会 就 悉 下 面 这 个 Spring 的 context: 命 名 空间 中 的 常用 
XML 声明 


<beans> 


<context:component-scan base-package="com.acme"/> 
</beans> 


在 上 面 的 示例 中 ，com.acme 包 就 会 被 扫描 ， 去 查找 任意 @Component 注解 的 类 ， 
那些 类 就 会 被 注册 为 Spring 容器 中 的 bean 。AnnotationConfigApplicationContext 
暴露 出 scan(String ...) 方 法 ， 允 许 相同 的 组 件 扫描 功能 : 


public static void main(String[] args) { 
AnnotationConfigApplicationContext ctx = new 
AnnotationConfigApplicationContext(); 
ctx.scan("com.acme"); 
ctx.refresh(); 
MyService myService = ctx.getBean(MyService.class); 


记得 @Configuration 类 是 使 用 @Component 进行 元 数据 注释 的 ， 所 以 它们 是 
组 件 扫 描 的 候选 者 ! 在 上 面 的 示例 中 ， 假 设 AppConfig 是 声明 在 com.acme 
包 (或 是 其 中 的 子 包 ) 中 的 ， 那 么 会 在 调用 scan() 方 法 时 被 找到 ， 在 调用 

refresh() 方 法 时 ， 所 有 它 的 @Bean 方法 就 会 被 处 理 并 注册 为 容器 中 的 bean。 


4.12.2.4 支持 Web 应 用 的 
AnnotationConfigWebApplicationContext 


WebApplicationContext Æ AnnotationConfigApplicationContext 的 变种 ， 


适用 于 AnnotationConfigWebApplicationContext ° 4 ti Spring 的 Servlet 监听 
器 ContextLoaderListener > Spring MVC 的 DispatcherServlet 等 时 ， 这 个 实现 类 
就 可 能 被 用 到 了 。 下 面 的 代码 是 在 web.xml 中 的 片段 ， 配 置 了 典型 的 Spring MVC 
的 Web 应 用 程序 。 注 意 contextClass 上 下 文 参 数 和 初始 化 参数 的 使 用 : 


<web -app> 
<!-- 配置 ContextLoaderListener 使 用 


AnnotationCconfigwebApplicationContext 来 代替 默认 的 XmlWebApplic 
ationContext --> 


<context-param> 
<param-name>contextClass</param-name> 
<param-value> org.springframework.web.context.support.An 


notationCon 
figwebApplicationContext 
</param-value> 
</context -param> 
<!-- 配置 位 置 必 须 包 含 一 个 或 多 个 去 号 或 空格 分 隔 的 完全 限定 
@Cconfiguration 类 。 完 全 限定 包 也 可 以 指定 于 组 件 扫描 --> 
<Context-param> 
<param-name>contextConfigLocation</param-name> 
<param-value>com.acme.AppConfig</param-value> 
</context -param> 
<1-- 普通 方式 启动 根 应 用 上 下 文 的 ContextLoaderListener --> 
<listener> 
<listener-class> org.springframework.web.context.Context 
LoaderListener 
</listener-class> 
</listener> 
<!-- 普通 方式 声明 Spring MVC 的 DispatcherServlet --> 
<servlet> 
<servlet -name>dispatcher</servlet -name> 
<servlet-class> org.springframework.web.servlet.Disp 
atcherServlet 
</servlet-class> 
<!-- 配置 DijspatcherServlet 使 用 
AnnotationCconfigwebApp1LicationContext 来 代替 默认 的 XmlwebAp 
plicationContext --> 
<init -param> 
<param-name>contextClass</param-name> 
<param-value> org.springframework.web.context.suppor 
t.Annotation 
Conf igwebApplicationContext 
</param-value> 
</init-param> 
<! - -配置 位 置 必 须 包 含 一 个 或 多 个 去 号 或 空格 分 隔 的 完全 限定 
@Configurationž--> 
<init-param> 
<param-name>contextConfigLocation</param-name> 
<param-value>com.acme.web.MvcConfig</param-value> 
</init-param> 
</servlet> 
<!-- 映射 所 有 的 请 求 到 /main/* 中 来 派发 servlet --> 
<servlet-mapping> 
<servlet-name>dispatcher</servlet-name> 
<url-pattern>/main/*</url-pattern> 
</servlet -mapping> 
</web-app> 


4.12.3 构成 基于 Java 的 配置 


4.12.3.1 使 用 @Import 注解 


就 像 Spring 的 XML 文件 中 使 用 的 <import/> 元 素 帮 助 模块 化 配置 一 样 ， 
@Import È 解 允 许 从 其 它 配置 类 中 加 载 @Bean 的 配置 : 


@Configuration 
public class ConfigA { 

public @Bean A a() { return new A(); } 
} 


@Configuration 
@Import(ConfigA.class) 
public class ConfigB { 
public @Bean B b() { return new B(); } 


现在 ， 当 实例 化 上 下 文 时 ， 不 需要 指定 ConfigA.class 和 ConfigB.class T > 1% 4% 
ConfigB 需要 被 显 式 提供 


public static void main(String[] args) { 
ApplicationContext ctx = new 
AnnotationConfigApplicationContext(ConfigB.class); 
// 现在 bean A 和 bean B 都 会 是 可 用 的 ,,， 
A a = ctx.getBean(A.class); 
B b = ctx.getBean(B.class); 


这 种 方式 简化 了 容器 的 实例 化 ， 仅 仅 是 一 个 类 需要 被 处 理 ， 而 不 是 需要 开发 人 员 在 
构造 时 记 住 很 多 大 量 的 @Configuration 类 。 


在 引入 的 @Bean 定义 中 注入 依赖 上 面 的 示例 是 可 行 的 ， 但 是 很 简单 。 在 很 多 
场景 中 ，bean 会 有 依赖 其 它 配置 的 类 的 依赖 。 当 使 用 XML Td ， 这 本 身 不 是 什么 
题 ， 因 为 没有 调用 编译 器 ' 而 且 我 们 可 以 仅仅 声 声明 ref="someBean" 并 且 相 信 
Spring 在 容器 初始 化 时 可 以 完成 。 当 然 ， 当 使 用 @Cconfiguration 的 类 时 ， 
Java 编译 器 在 配置 模型 上 放置 约束 ， 对 其 它 bean 的 引用 必须 是 符合 Java 语法 
的 。 


幸运 的 是 ， 解 决 这 个 问题 分 层 简 单 。 记 得 @Configuration 类 最 终 是 容器 中 的 bean- 
这 就 是 说 它们 可 以 像 其 它 bean 那样 利用 @Autowired 注入 元 数据 ! 我 们 来 看 一 S 
更 加 真实 的 语义 ， 有 几 个 @Configuration 类 ， 每 个 都 依赖 声明 在 其 它 类 中 的 

bean : 


@Configuration 
public class ServiceConfig { 
private @Autowired AccountRepository accountRepository; 
public @Bean TransferService transferService() { 
return new TransferServiceImpl(accountRepository); 
} 


@Configuration 
public class RepositoryConfig { 
private @Autowired DataSource dataSource; 
public @Bean AccountRepository accountRepository() { 
return new JdbcAccountRepository(dataSource); 
} 


@Configuration 
@Import({ServiceConfig.class, RepositoryConfig.class}) 
public class SystemTestConfig { 
public @Bean DataSource dataSource() { /* 返回 新 的 数据 源 */ } 


public static void main(String[] args) { 
ApplicationContext ctx = new 
AnnotationConfigApplicationContext(SystemTestConfig.clas 
s); 
// 所 有 的 装配 都 使 用 配置 的 类 ,.. 
TransferService transferService = ctx.getBean(TransferServic 
e.class); transferService.transfer(100.00, "A123", "C456"); 


} 


完全 限定 引入 的 bean 便于 导航 


在 上 面 的 场景 中 ， 使 用 @Autowired 工作 正常 ， 提 供 所 需 的 模块 化 ， 但 是 准确 地 决 
定 在 哪儿 声明 自动 装配 的 bean 还 是 有 些 含糊 。 比 如 ， 作 为 开发 者 来 看 待 
ServiceConfig ， 你 如 何 准 确 知道 @Autowired AccountRepository 在 哪里 声明 的 ? 
它 没有 显 式 地 出 现 在 代码 中 ， 这 可 能 很 不 错 。 要 记得 SpringSource Tool Suite 提 
isla para ey 象 是 如 何 装配 起 来 的 图 片 - 那 可 能 就 是 你 所 需要 的 。 而 

你 的 Java IDE 可 以 很 容器 发 现 所 有 的 声明 ， 还 有 使 用 的 AccountRepository 
， 也 会 很 快 地 给 你 展示 出 @Bean 方法 的 位 置 和 返回 的 类 型 。 


在 这 种 歧义 不 被 接受 和 你 想 有 直接 从 IDE 中 从 一 个 @Configuration 类 到 另 一 个 导 
航 的 情景 中 ， 要 考虑 自动 装配 配置 类 的 本 身 : 


@Configuration 
public class ServiceConfig { 
private @Autowired RepositoryConfig repositoryConfig; 
public @Bean TransferService transferService() { 
// 通过 配置 类 到 @Bean 方 法 的 导航 ! 
return new 
TransferServiceImpl1(repositoryConfig.accountReposito 


ry()); 


在 上 面 的 情形 中 ， 定 义 AccountRepository 是 完全 明确 的 。 而 ServiceConfig 却 紧 
% 48 3] RepositoryConfig 中 了 ; 这 就 需要 我 们 来 权衡 了 。 这 种 紧 耦 合 可 以 使 用 
基于 接口 或 抽象 基 类 的 @Configuration 类 来 减轻 。 考 虑 下 面 的 代码 : 


@Configuration 
public class ServiceConfig { 
private @Autowired RepositoryConfig repositoryConfig; 
public @Bean TransferService transferService() { 
return new 
TransferServiceImpl(repositoryConfig.accountRepository( ) 


); 
} 
} 
@Configuration 
public interface RepositoryConfig { 

@Bean AccountRepository accountRepository(); 
} 


@Configuration 
public class DefaultRepositoryConfig implements RepositoryConfig 
{ 
public @Bean AccountRepository accountRepository() { 
return new JdbcAccountRepository(...); 
} 
} 


@Configuration 
@Import({ServiceConfig.class, DefaultRepositoryConfig.class}) 
// 导入 具体 的 配置 ! 
public class SystemTestConfig { 

public @Bean DataSource dataSource() { /* 返回 数据 源 */ } 
} 


public static void main(String[] args) { 

ApplicationContext ctx 

= new AnnotationConfigApplicationContext(SystemTestConfi 

g.class); 

TransferService transferService = ctx.getBean(TransferServic 
e.class); 

transferService.transfer(100.00, "A123", "C456"); 
} 


现在 ServiceConfig 和 DefaultRepositoryConfig 的 耦合 就 比较 松 了 ， 并 且 内 建 的 
IDE 工具 也 一 直 有 效 : 对 于 开发 人 员 来 说 会 更 加 简单 地 获取 RepositoryConfig 实现 
类 的 类 型 层次 。 以 这 种 方式 ， 导 航 @Configuration 类 和 它们 的 依赖 就 和 普通 的 基于 
接口 代码 的 导航 过 程 没有 任何 区 别 了 。 


4.12.3.2 结合 Java 和 XML 配置 


Spring 的 @Configuration 类 并 不 是 完全 100% 地 支持 Spring XML 替换 的 。 一 些 基 
本 特 性， 比如 Spring XML 的 命名 空间 会 保持 在 一 个 理想 的 方式 下 去 配置 容器 。 在 
XML 便于 使 用 或 是 必须 要 使 用 的 情况 下 ， 你 也 有 另外 一 个 选择 : 以 “XML 为 中 

心 ” 的 方式 来 实例 化 容器 ， 比 如 ，ClassPathXmlApplicationContext， 或 者 以 “ Java 
为 中 心 "的 方式 ， 使 用 AnnotationConfigurationApplicationContext 和 
@ImportResource 注解 来 引 入 需要 的 XML ° 


以 “XML 为 中 心 "使 用 @Configuration 类 从 一 种 特定 的 方式 的 包含 @Configuration 
类 的 XML 文件 启动 Spring 容器 是 不 错 的 。 比如， 在 使 用 了 Spring XML 的 大 型 的 
代码 库 中 ， 根 据 需 要 并 从 已 有 的 XML 文件 中 创建 @Configuration 类 是 很 简单 的 。 
在 下 面 ， 你 会 发 现在 这 种 "XML 为 中 心 " 情 形 下 ， 使 用 @Configuration 类 的 选择 。 


以 普通 的 Spring <bean/> 元 素 声 明 @Configuration 类 


要 记得 @Configuration 的 类 最 终 仅 仅 是 容器 中 的 bean。 在 这 个 示例 中 ， 我 们 创建 
了 名 为 AppConfig 的 @Configuration 类 ， 并 且 将 它 包含 在 system-test-config.xml 
文件 中 作为 <bean/> 的 定义 。 因 为 开启 了 <context:annotation-config/> 配 
置 ， 容 器 会 识别 @Configuration 注解 ， 以 合适 的 方式 处 理 声 明 在 AppConfig 中 
@Bean 方法 。 


@Configuration 
public class AppConfig { 
private @Autowired DataSource dataSource; 
public @Bean AccountRepository accountRepository() { 
return new JdbcAccountRepository(dataSource); 


public @Bean TransferService transferService() { 
return new TransferService(accountRepository()); 
} 


} 


system-test-config. xml 
<beans> 
<!-- 开局 处 理 注 解 功 能 ， 比 如 @Autowired 和 @Cconfiguration --> 
<context :annotation-config/> 
<context:property-placeholder 
location="classpath:/com/acme/jdbc.properties"/> 
<bean class="com.acme.AppConfig"/> 
<bean class="org.springframework.jdbc.datasource.DriverManag 
erData Source"> 
<property name="url" value="${jdbc.url}"/> 
<property name="username" value="${jdbc.username}"/> 
<property name="password" value="${jdbc.password}"/> 
</bean> 
</beans> 


jdbc.properties 
jdbc.url=jdbc:hsgqldb:hsql://localhost/xdb 
jdbc.username=sa 

jdbc.password= 


public static void main(String[] args) { 

ApplicationContext ctx 

= new ClassPathXmlApplicationContext("classpath:/com/acm 

e/system-t est-config.xml"); 

TransferService transferService = ctx.getBean(TransferServic 
e.class); 

ULI ee 
} 


i 
汪 意 


在 上 面 的 system-test-config.xml 文件 中 ，AppConfig 的 <bean/> 定义 没有 上 声 
明 id 元 素 。 这 么 做 也 是 可 以 接受 的 ， 就 不 必 让 其 它 bean 去 引用 它 了 。 同 时 也 
就 不 可 能 从 容器 中 通过 明确 的 名 称 来 获取 它 了 。 同 样 地 ，DataSource bean ° 
通过 类 型 自动 装配 ， 那 么 明确 的 bean id 就 不 严格 要 求 了 。 


使 用 <context:component-scan/> 来 检索 @Configuration 类 


因为 @Configuration 是 使 用 @Component 来 元 数据 注解 的 ， 被 @Configuration 注 
解 的 类 是 自动 作为 组 件 扫 描 的 候选 者 的 。 使 用 上 面相 同 的 语义 ， 我 们 可 以 重新 来 定 
SL system-test-config.xml 文件 来 利用 组 件 扫描 的 优点 。 注 意 这 种 情况 下 ， 我 们 不 
需要 明确 地 声明 <context:annotation-config/> ， 因 

为 <context:component-scan/> 开局 了 相同 的 功能 。 


system-test-config. xml 
<beans> 
<!-- 选择 并 注册 AppConfig 作 为 bean --> 
<context:component-scan base-package="com.acme"/> 
<context:property-placeholder 
location="classpath:/com/acme/jdbc.properties"/> 
<bean class="org.springframework.jdbc.datasource.DriverManag 
erData Source"> 
<property name="url" value="${jdbc.url}"/> 
<property name="username" value="${jdbc.username}"/> 
<property name="password" value="${jdbc.password}"/> 
</bean> 
</beans> 


4%] T @lmportResource 导入 XML 47@Configuration 类 为 中 心 在 @Configuration 
类 作为 配置 容器 主要 机 制 的 应 用 程序 中 ， 使 用 一 些 XML 还 是 必要 的 。 在 这 些 情况 
中 ， 仅 仅 使 用 @ImportResource 来 定义 XML 就 可 以 了 。 这 么 来 做 就 实现 了 “Java 
为 中 心 " 的 方式 来 配置 容器 并 保持 XML 在 最 低 限度 。 


@Configuration 
@ImportResource("classpath:/com/acme/properties-config.xml") 
public class AppConfig { 

private @Value("${jdbc.url}") String url; 

private @Value("${jdbc.username}") String username; 

private @Value("${jdbc.password}") String password; 

public @Bean DataSource dataSource() { 

return new DriverManagerDataSource(url, username, passwo 

rd); 


} 
} 


properties-config. xml 
<beans> 
<context:property-placeholder 
location="classpath:/com/acme/jdbc.properties"/> 
</beans> 


jdbc.properties 
jdbc.url=jdbc:hsqldb:hsql://localhost/xdb 
jdbc.username=sa 

jdbc .password= 


public static void main(String[] args) { 

ApplicationContext ctx 

= new AnnotationConfigApplicationContext(AppConfig. clas 

s); 

TransferService transferService = ctx.getBean(TransferServic 
e.class); 

L ares 
} 
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在 今日 的 企业 环境 中 ， 把 面向 对 象 的 软件 和 关系 数据 库 一 起 使 用 可 能 是 相当 麻烦 、 
浪费 时 间 的 。Hibernate 是 一 个 面向 Java 环 境 的 对 象 /关系 数据 库 映 射 工 具 。 对 象 / 关 
系数 据 库 映射 (object/relational mapping (ORM)) 这 个 术语 表示 一 种 技术 ， 用 来 把 对 
象 模型 表示 的 对 象 映 射 到 基于 SQL 的 关系 模型 数据 结构 中 去 。 


Hibernate 不 仅仅 管理 Java 类 到 数据 库 表 的 映射 (包括 Java 数 据 类 型 到 SQL 数据 类 
型 的 映射 ) ， 还 提供 数据 查询 和 获取 数据 的 方法 ， 可 以 大 幅度 减少 开发 时 人 工 使 用 
SQL 和 JDBC 处 理 数据 的 时 间 。 


Hibernate 的 目标 是 对 于 开发 者 通常 的 数据 持久 化 相关 的 编程 任务 ， 解 放 其 中 的 
95%。 对 于 以 数据 为 中 心 的 程序 来 说 ,它们 往往 只 在 数据 库 中 使 用 存储 过 程 来 实现 商 
业 逻 辑 ,Hibernate 可 能 不 是 最 好 的 解决 方案 ;对 于 那些 在 基于 Java 的 中 间 层 应 用 中 ， 
它们 实现 面向 对 象 的 业务 模型 和 商业 逮 辑 的 应 用 ，Hibernate 是 最 有 用 的 。 不 管 怎 
样 ，Hibernate 一 定 可 以 帮助 你 消除 或 者 包装 那些 针对 特定 厂商 的 SQL 代码 ， 并 且 帮 
你 把 结果 集 从 表格 式 的 表示 形式 转换 到 一 系列 的 对 象 去 。 


如 果 你 对 Hibernate 和 对 象 /关系 数据 库 映 射 还 是 个 新 手 ， 或 者 其 至 对 Java 也 不 熟 
悉 ， 请 按照 下 面 的 步骤 来 学 习 。 


1. 阅读 第 1 章 EA ， 这 是 一 篇 包含 详细 的 逐步 指导 的 指南 。 本 指南 的 
源 代 码 包含 在 发 行 包 中 ， 你 可 以 在 doc/reference/tutorial/ 目录 下 找到 。 


2. 阅读 第 2 章 体系 结构 (Architecture) 来 理解 Hibernate 可 以 使 用 的 环境 。 


3. 查看 Hibernate 发 行 包 中 的 eg/ 目录 ， 里 面 有 一 个 简单 的 独立 运行 的 程序 。 把 
你 的 JDBC 了 驱动 拷贝 到 lib/ 目录 下 ， 修 改 一 
下 src/hibernate.properties ,指定 其 中 你 的 数据 库 的 信息 。 进 入 命令 行 ， 
切换 到 你 的 发 行 包 的 目录 ， 输 入 ant eg (使 用 了 Ant) ,或 者 在 Windows 操 作 
系统 中 使 用 build eg 。 


4. 把 这 份 参考 文档 作为 你 学 习 的 主要 信息 来 源 。 
5. 在 Hibernate 的 网 站 上 可 以 找到 经 常 提问 的 问题 与 解答 (FAQ)。 


6. 在 Hibernate 网 站 上 还 有 第 三 方 的 演示 、 示 例 和 教程 的 链接 。 


7. Hibernate 网 站 的 “社区 (Community Area)’ 是 讨论 关于 设计 模式 以 及 很 多 整合 方 
(Tomcat, JBoss AS, Struts, EJB, 等 等 ) 的 好 地 方 。 


如 果 你 有 问题 ， 请 使 用 Hibernate 网 站 上 链接 的 用 户 论 坛 。 我 们 也 提供 一 个 JIRA 问 
题 追 踪 系 统 ， 来 搜集 bug 报 告 和 新 功能 请 求 。 如 果 你 对 开发 Hibernate 有 兴趣 ， 请 加 
入 开发 者 的 邮件 列表 。 (Hibernate 网 站 上 的 用 户 论坛 有 一 个 中 文 版 面 ，JavaEye 也 
有 Hibernate 中 文 版 面 ,您 可 以 在 那里 交流 问题 与 经 验 。) 


商业 开发 、 产 品 支持 和 Hibernate 培 训 可 以 通过 JBoss lnc. 获 得 。 (请 查阅 : 
http://www.hibernate.org/SupportTraining/) ° Hibernate 是 一 个 专业 的 开放 源 代 码 
项 目 (Professional Open Source project)， 也 是 JBoss Enterprise Middleware 
System(JEMS),JBoss 企 业 级 中 间 件 系统 的 一 个 核心 组 件 。 


1. 翻译 说 明 


本 文档 的 翻译 是 在 网 络 上 协作 进行 的 ， 也 会 不 断根 据 Hibernate 的 升级 进行 更 新 。 提 
供 此 文档 的 目的 是 为 了 减缓 学 习 Hibernate 的 坡度 ， 而 非 代替 原文 档 。 lila ied 
A AEJ AQT AAR EER SUM EIEA HW > RARILEME BR > BAK 
言 赐 教 ， 报 告 到 如 下 email 地 址 : cao at redsaga.com 


Hibernate 版 本 3 的 翻译 由 满江红 翻译 团队 (RedSaga Translate Team) 集 体 进 行 ， 这 
也 是 一 次 大 规模 网 络 翻 译 的 试验 。 在 不 到 20 天 的 时 间 内 ， 我 们 完成 了 两 百 多 页 文档 
的 翻译 ， 这 一 成 果 是 通过 十 几 位 网 友 集 体 努 力 完 成 的 。 通 过 这 次 翻译 ， 我 们 也 有 了 

一 套 完 整 的 流程 ， 从 初 译 、 技 术 审 核 一 直到 文字 审核 、 发 布 。 ee 
继续 完 善 我 们 的 翻译 流程 ， 并 翻译 其 他 优秀 的 java 开源 资料 ， 请 期 待 。 
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V3.2 版 本 在 2006 年 11 月 份 由 章 晓 钢 更 新 。 
关于 我 们 
满江红 .开源 , http://www.redsaga.com 


从 成 立 之 初 就 致力 于 Java 开 放 源 代码 在 中 国 的 传播 与 发 展 ,与 国内 多 个 Java 团 体 及 
出 版 社 有 深入 交流 。 坚 持 少 说 多 做 的 原则 ， 目 前 有 两 个 团队 ，“OpenDoc 团 队 ” 与 “ 翻 
译 团 队 ”， 本 翻译 文档 即 为 翻译 团队 作品 。OpenDoc 团 队 已 经 推出 包括 Hibernate、 
iBatis、Spring、WebWork 的 多 份 开放 文档 ， 并 于 2005 年 5 月 在 Hibernate 开 放 文 档 
基础 上 扩充 成 书 ， 出 版 了 原创 书籍 : 《深入 浅 出 Hibernate》， 本 书 400 余 页 ， 适 合 
各 个 层次 的 Hibernate 用 户 。(http://www.redsaga.com/hibernate_book.html) 施 请 支 
持 。 


北京 Java 用 户 组 , http://www.bjug.org 


eh Java User Group， 民 间 技 术 交 流 组 织 ， 成 立 于 2004 年 6 月 。 以 交流 与 共享 为 

> 每 两 周 举行 一 次 技术 聚会 活动 。BJUG 的 目标 是 ， 通 过 小 部 分 人 的 努力 ， 形 
成 一 个 技术 社 群 ， 创建 良好 的 交流 氛围 ， 并 将 新 的 技术 和 思想 推广 到 整个 |T 界 ， 让 
我 们 共同 进步 。 


Java 视 线 , http://www.javaeye.com 


Java 视 线 在 是 Hibernate 中 文 论 坛 〈 http://www.hibernate.org.cn ，Hibernate 中 文 
论坛 是 中 国 最 早 的 Hibernate 专 业 用 户 论坛 ， 为 Hibernate 在 中 国 的 推广 做 出 了 巨大 
的 贡献 ) 基础 上 发 展 起 来 的 Java 深 度 技 术 网 站 ， 目 标 是 成 为 一 个 高 品质 的 ， 有 思想 
深度 的 、 原 创 精 神 aa ipa 站 ， 为 软件 从 业 人 员 提 供 一 个 自由 的 交流 技 
术 > 交流 思想 和 交流 信 ， 息 的 平台 


致谢 
还 有 一 些 朋 友 给 我 们 发 来 了 勘误 ， 在 此 致谢 : Kurapica > BH > BA © 


2. 版 权 声 明 


Hibernate 美 文 文档 属于 Hibernate 发 行 包 的 一 部 分 ， 遵 循 LGPL 协 议 。 本 翻译 版 本 同 
样 遵 特 LGPL 协议。 参与 翻译 的 译 者 一 致 同意 放弃 除 署 名 权 外 对 本 翻译 版 本 的 其 它 
权利 要 求 。 


您 可 以 自由 链接 、 下 载 、 传 播 此 文档 ， 或 者 放置 在 您 的 网 站 上 ， 基 至 作为 产品 的 一 
部 分 发 行 。 但 前 提 是 必须 保证 全 文 完整 转载 ， 和 包括 完整 的 版 权 信息 和 作 译 者 声明 ， 
并 不 能 违反 LGPL 协 议 。 这 里 “完整 "的 含义 是 ， 不 能 进行 任何 删除 /增添 /注解 。 若 有 
删除 /增添 /注解 ， 必 须 逐 段 明 确 声明 那些 部 分 并 非 本 文档 的 一 部 分 。 
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第 三 部 分 - EventManager web 应 用 程序 


1. 编写 大 本 的 servlet 
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1 .1 m Ay) E 
本 章 是 面向 Hibernate 初 学 者 的 一 个 入 门 教程 。 我 们 从 一 个 使 用 驻 留 内 存 式 (in- 
memory) 数 据 库 的 简单 命令 行 应 用 程序 开始 , 用 易于 理解 的 方式 逐步 开发 。 


本 章 面向 Hibernate 初 学 者 ， 但 需要 Java 和 SQL 知识 。 它 是 在 Michael Goegl 所 写 的 
指南 的 基础 上 完成 的 。 在 这 里 ， 我 们 称 第 三 方 库 文 件 是 指 JDK 1.4 和 5.0。 若 使 用 
JDK1.3， 你 可 能 需要 其 它 的 库 文 件 。 


本 章 的 源 代码 已 包含 在 发 布 包 中 ， 位 于 doc/reference/tutorial/ 目录 下 。 


1.2. 第 一 部 分 一 第 一 个 Hibernate 应 用 程序 


首先 我 们 将 创建 一 个 简单 的 基于 控制 台 的 (console-based)Hibernate 应 用 程序 。 由 
于 我 们 使 用 Java 数 据 库 (HSQL DB)， 所 以 不 必 安 装 任何 数据 库 服务 器 。 


假设 我 们 希望 有 一 个 小 应 用 程序 可 以 保存 我 们 希望 参加 的 活动 (events) 和 这 些 活 
动 主办 方 的 相关 信息 。 ( 译 者 注 : 在 本 教程 的 后 面部 分 ， 我 们 将 直接 使 用 event 而 
不 是 它 的 中 文 翻译 "活动"*， VARIG © ) 


我 们 所 做 的 第 一 件 事 就 是 创建 我 们 的 开发 目录 ， 并 且 把 所 有 需要 用 到 的 Java 库 文件 
放 进 去 。 解 压缩 从 Hibernate 网 站 下 载 的 Hibernate 发 布 包 ， 并 把 /1ib 目录 下 所 有 
需要 的 库 文件 拷 到 我 们 新 建 开发 目录 下 的 /1ib 目录 下 。 看 起 来 就 像 这 样 : 


+lib 
antlr.jar 
cglib.jar 
asm.jar 
asm-attrs.jars 
commons-collections. jar 
commons-logging. jar 
ehcache. jar 
hibernate3. jar 
jta.jar 
dom4j , jar 
log4j.jar 


到 编写 本 文 时 为 止 ， 这 些 是 Hibernate 运 行 所 需要 的 最 小 库 文件 集合 (注意 我 们 也 拷 
NY Hibernate3.jar， 这 个 是 最 主要 的 文件 ) 。 你 正 使 用 的 Hibernate 版 本 可 能 需 

比 这 更 多 或 少 一 些 的 库 文 件 。 请 参见 发 布 包 中 的 1ib/ 目录 下 的 README.txt ， 
以 获取 更 多 关于 所 需 和 可 选 的 第 三 方 库 文 件 信息 (事实 上 ，Log4j 并 不 是 必须 的 库 
文件 ， 但 被 许多 开发 者 所 喜欢 ) © 


接 下 来 我 们 创建 一 个 类 ， 用 来 代表 那些 我 们 希望 储存 在 数据 库 里 的 event 。 


1.2.1. 第 一 个 class 
我 们 的 第 一 个 持久 化 类 是 一 个 带 有 一 些 属 性 (property) 的 简单 JavaBean 类 : 


package events; 
import java.util.Date; 


public class Event { 
private Long id; 


private String title; 
private Date date; 


public Event() {} 


public Long getId() { 
return id; 
} 


private void setId(Long id) { 
this.id = id; 
} 


public Date getDate() { 
return date; 
} 


public void setDate(Date date) { 
this.date = date; 
} 


public String getTitle() { 
return title; 
} 


public void setTitle(String title) { 
this.title = title; 
} 


你 可 以 看 到 这 个 类 对 属性 的 存 取 方法 〈getter and setter method) 使 用 了 标准 
JavaBean 命 名 约定 ， 同 时 把 类 属性 (field) 的 访问 级 别 设 成 私有 的 (private) 。 这 
是 推荐 的 设计 ， 但 并 不 是 必须 的 。Hibernate 也 可 以 直接 访问 这 些 field， 而 使 用 访问 
方法 (accessor method) 的 好 处 是 提供 了 重 构 时 的 健壮 性 (robustness) 。 为 了 
通过 反射 机 制 (Reflection) 来 实例 化 这 个 类 的 对 象 ， 我 们 需要 提供 一 个 无 参 的 构 
造 器 (no-argument constructor) ° 


对 一 特定 的 event，id 属性 持 有 唯一 的 标识 符 (identifier) 的 值 。 如 果 我 们 希望 使 
用 Hibernate 提 供 的 所 有 特性 ， 那 么 所 有 的 持久 化 实体 (persistent entity) 类 (这 里 
也 包括 一 些 次 要 依赖 类 ) 都 需要 一 个 这 样 的 标识 符 属 性 。 而 事实 上 ， 大 多 数 应 用 程 
序 (特别 是 web 应 用 程序 ) 都 需要 通过 标识 符 来 区 别 对 象 ， 所 以 你 应 该 考虑 使 用 标 
识 符 属 性 而 不 是 把 它 当 作 一 种 限制 。 然 而 ， 我 们 通常 不 会 操作 对 象 的 标识 

(identity) ， 因 此 它 的 setter 方 法 的 访问 级 别 应 该 声明 private。 这 样 当 对 象 被 保存 
的 时 候 ， 只 有 Hibernate 可 以 为 它 分 配 标识 符 值 。 你 可 看 到 Hibernate 可 以 直接 访问 
public，private 和 protected 的 访问 方法 和 field。 所 以 选择 哪 种 方式 完全 取决 于 你 ， 
你 可 以 使 你 的 选择 与 你 的 应 用 程序 设计 相 吻 合 。 


所 有 的 持久 化 类 (persistent classes) 都 要 求 有 无 参 的 构造 器 ， 因 为 Hibernate 必 须 
使 用 Java 反 射 机 制 来 为 你 创建 对 象 。 构 造 器 (constructor) 的 访问 级 别 可 以 是 
private， 然 而 当 生 成 运行 时 代理 (runtime proxy) 的 时 候 则 要 求 使 用 至 少 是 
package 级 别 的 访问 控制 ， 这 样 在 没有 字 节 码 指 令 〈bytecode instrumentation) 的 
情况 下 ， 从 持久 化 类 里 获取 数据 会 更 有 效率 。 


把 这 个 Java 源 代码 文件 放 到 开发 目录 下 的 src 目录 里 ， 注 意 包 位 置 要 正确 。 现 在 
这 个 目录 看 起 来 应 该 像 这 样 : 


+lib 
<Hibernate and third-party libraries> 
+SrC 
+events 
Event.java 


下 一 步 ， 我们 把 这 个 持久 化 类 的 信息 告诉 Hibernate ° 


1.2.2. 映射 文件 


Hibernate 需 要 知道 怎样 去 加 载 (load) 和 存储 (store) 持久 化 类 的 对 象 。 这 正 是 
Hibernate 了 映射 文件 发 挥 作用 的 地 方 。 了 映射 文件 告诉 Hibernate 它 ， 应 该 访问 数据 库 
(database) 里 面 的 哪个 表 (table) 及 应 该 使 用 表 里 面 的 哪些 字段 (column) 。 


一 个 映射 文件 的 基本 结构 看 起 来 像 这 样 : 


<?xml version="1.0"?> 
<!DOCTYPE hibernate-mapping PUBLIC 
"-//Hibernate/Hibernate Mapping DTD 3.0//EN" 
"http://hibernate.sourceforge.net/hibernate-mapping-3.0. 
dtd"> 


<hibernate-mapping> 


[...] 


</hibernate-mapping> 


注意 Hibernate 的 DTD 是 非常 复杂 的 。 你 的 编辑 器 或 者 IDE 里 使 用 它 来 自动 完成 那些 
用 来 映射 的 XML 元 素 (element) FAT (attribute) 。 你 也 可 以 在 文本 编辑 器 里 打 
开 DTD 一 这 是 最 简单 的 方式 来 概览 所 有 的 元 素 和 attribute， 并 查看 它们 的 缺 省 值 以 
及 注释 。 注 意 Hibernate 不 会 从 Web 加 载 DTD 文 件 ， 但 它 会 首先 在 应 用 程序 的 
classpath 中 查找 。DTD 文 件 已 包括 在 hibernate3.jar 里 ， 同 时 也 在 Hibernate 发 
布 包 的 src/ 目录 下 。 


为 缩短 代码 长 度 ， 在 以 后 的 例子 里 我 们 会 省 略 DTD 的 声明 。 当 然 ， 在 实际 的 应 用 程 
序 中 ，DTD 声 明 是 必须 的 。 

在 hibernate-mapping 标签 (tag) 之 间 , 含有 一 个 class 元 素 。 所 有 的 持久 化 
实体 类 〈 再 次 声明 ， 或 许 接 下 来 会 有 依赖 类 ， 就 是 那些 次 要 的 实体 ) 都 需要 一 个 这 
样 的 映射 ， 来 把 类 对 象 映 射 到 SQL 数据 库 里 的 表 。 


<hibernate-mapping> 
<class name="events.Event" table="EVENTS"> 
</class> 
</hibernate-mapping> 
到 目前 为 止 ， 我 们 告诉 了 Hibernate 怎 样 把 Events 类 的 对 象 持 久 化 到 数据 库 
的 EVENTS 表 里 ， 以 及 怎样 从 EVENTS 表 加 载 到 Events 类 的 对 象 。 每 个 实例 对 
应 着 数据 库 表 中 的 一 行 。 现 在 我 们 将 继续 讨论 有 关 唯 一 标识 符 属 性 到 数据 库 表 的 映 


射 。 另 外 ， 由 于 我 们 不 关心 怎样 处 理 这 个 标识 符 ， 我 们 就 配置 由 Hibernate 的 标识 符 
生成 策略 来 产生 代理 主键 字段 。 


<hibernate-mapping> 


<class name="events.Event" table="EVENTS"> 
<id name="id" column="EVENT_ID"> 
<generator class="native"/> 
</id> 
</class> 


</hibernate-mapping> 


id 元 素 是 标识 符 属 性 的 声明 ， name="id" 声明 了 Java 属 性 的 名 字 一 Hibernate 
会 使 用 getId() 和 setId() 来 访问 它 。 column 属性 则 告诉 Hibernate, 我 们 使 
用 EVENTS 表 的 哪个 字段 作为 主键 。 哗 套 的 generator 元 素 指 定 了 标识 符 生成 策 
略 ， 在 这 里 我 们 指定 native ， 它 根据 已 配置 的 数据 库 (FS) 自动 选择 最 佳 的 标 
识 符 生 成 策略 。Hibernate 支 持 由 数据 库 生 成 ， 全 局 唯一 性 (globally unique) 和 应 
用 程序 指定 (或 者 你 自己 为 任何 已 有 策略 所 写 的 扩展 ) 这 些 策略 来 生成 标识 符 。 


最 后 我 们 在 映射 文件 里 面包 含 需要 持久 化 属性 的 声明 。 黑 认 情况 下 ， 类 里 面 的 属性 
都 被 视 为 非 持 久 化 的 : 


<hibernate-mapping> 


<class name="events.Event" table="EVENTS"> 
<id name="id" column="EVENT_ID"> 
<generator class="native"/> 
</id> 
<property name="date" type="timestamp" column="EVENT_DAT 
E"/> 
<property name="title"/> 
</class> 


</hibernate-mapping> 


和 id 元 素 一 样 ， property 元 素 的 name 属性 告诉 Hibernate 使 用 哪个 getter 和 
setter 方 法 。 在 此 例 中 ，Hibernate 会 寻找 getDate()/setDate() ,以 
及 getTitle()/setTitle() 。 


为 什么 date 属性 的 映射 含有 column attribute， 而 title 却 没 有 ? 当 没 有 设 
Æ column attribute 的 时 候 ，Hibernate 缺 省 地 使 用 JavaBean 的 属性 名 作为 字段 
名 。 对 于 title ， 这 样 工作 得 很 好 。 然 而 ， date 在 多 数 的 数据 库 里 ， 是 一 个 保 
留 关 键 字 ， 所 以 我 们 最 好 把 它 映射 成 一 个 不 同 的 名 字 。 


另 一 有 趣 的 事情 是 title 属性 缺少 一 个 type attribute。 我 们 在 映射 文件 里 声明 
并 使 用 的 类 型 ， 却 不 是 我 们 期 望 的 那样 ， 是 Java 数 据 类 型 ， 同 时 也 不 是 SQL 数据 库 
的 数据 类 型 。 这 些 类 型 就 是 所 谓 的 Hibernate 映射 类 型 (mapping types) ， 它 们 能 
把 Java 数 据 类 型 转换 到 SQL 数据 类 型 ， 反 之 亦 然 。 再 次 重申 ， 如 果 在 映射 文件 中 没 
有 设置 type 属性 的 话 ，Hibernate 会 自己 试 着 去 确定 正确 的 转换 类 型 和 它 的 映射 
类 型 。 在 某 些 情况 下 这 个 自动 检测 机 制 (在 Java 类 上 使 用 反射 机 制 ) 不 会 产生 你 所 


期 待 或 需要 的 缺 省 值 。 date 属性 就 是 个 很 好 的 例子 ，Hibernate 无 法 知道 这 个 属 
性 ( java.util.Date 类 型 的 ) 应 该 被 映射 成 : SQL date ， 或 timestamp ， 
还 是 time 字段 。 在 此 例 中 ， 把 这 个 属性 映射 成 timestamp 转换 器 ， 这 样 我 们 
预 留 了 日 期 和 时 间 的 全 部 信息 。 


应 该 把 这 个 映射 文件 保存 为 Event.hbm.xml ， 且 就 在 Event Java 类 的 源 文件 目 
录 下 。 映 射 文件 可 随意 地 命名 ， 但 hbm.xml 的 后 组 已 成 为 Hibernate 开 发 者 社区 的 
约定 。 现 在 目录 结构 看 起 来 应 该 像 这 样 : 


+lib 

<Hibernate and third-party libraries> 
+Src 

+events 

Event.java 

Event .hbm. xml 


我 们 继续 进行 Hibernate 的 主要 配置 。 


1.2.3. Hibernate 配 置 


现在 我 们 已 经 有 了 一 个 持久 化 类 和 它 的 映射 文件 ， 该 是 配置 Hibernate 的 时 候 了 。 在 

此 之 前 ， 我 们 需要 一 个 数据 库 。 HSQL DB 是 种 基于 Java 的 SQL 数据 库 管理 系统 
(DBMS) ， 可 以 从 HSQL DB 的 网 站 上 下 载 。 实 际 上 ， 你 只 需 下 载 的 包 中 

的 hsqldb.jar 文件 ， 并 把 这 个 文件 放 在 开发 文件 夹 的 1ib/ 目录 下 即 可 。 


在 开发 的 根 目 录 下 创建 一 个 data 目录 一 这 是 HSQL DB 存储 数据 文件 的 地 方 。 此 
时 在 data 目 录 中 运 

行 java -classpath ../lib/hsqldb.jar org.hsqldb.Server 就 可 局 动 数 据 
库 。 你 可 以 在 log 中 看 到 它 的 启动 ， 及 绑 定 到 TCP/HIP 套 结 字 ， 这 正 是 我 们 的 应 用 程 
序 稍 后 会 连接 的 地 方 。 如 果 你 希望 在 本 例 中 运行 一 个 全 新 的 数据 库 ， 就 在 窗口 中 按 
下 CTRL + C 来 关闭 HSQL 数 据 库 ， 并 删除 datas 目录 下 的 所 有 文件 ， 再 重新 局 
动 HSQL 数 据 库 。 


Hibernate 是 你 的 应 用 程序 里 连接 数据 库 的 那 层 ， 所 以 它 需 要 连接 用 的 信息 。 连 接 

(connection) 是 通过 一 个 也 由 我 们 配置 的 JDBC 连 接 池 (connection pool) 来 完 
成 的 。Hibernate 的 发 布 包 里 包含 了 许多 开源 的 (open source) 连接 池 ， 但 在 我 们 
例子 中 使 用 Hibernate 内 置 的 连接 池 。 注 意 ， 如 果 你 希望 使 用 一 个 产品 级 
(production-quality) 的 第 三 方 连接 池 软 件 ， 你 必须 拷贝 所 需 的 库 文件 到 你 的 
classpath 下 ， 并 使 用 不 同 的 连接 池 设 置 。 


为 了 保存 Hibernate 的 配置 ， 我 们 可 以 使 用 一 个 简单 的 hibernate.properties X 
件 ， 或 者 一 个 稍微 复杂 的 hibernate.cfg.xml ， 甚 至 可 以 完全 使 用 程序 来 配置 
Hibernate。 多 数 用 户 更 喜欢 使 用 XML 配置 文件 : 


<?xml version='1.0' encoding='utf-8'?> 
<!DOCTYPE hibernate-configuration PUBLIC 
"-//Hibernate/Hibernate Configuration DTD 3.0//EN" 
"http://hibernate.sourceforge.net/hibernate-configuratio 
n-3.0.dtd"> 


<hibernate-configuration> 


<session-factory> 


<!-- Database connection settings --> 

<property name="connection.driver_class">org.hsqldb. jdbc 
Driver</property> 

<property name="connection.url">jdbc:hsqldb:hsql://local 
host</property> 


<property name="connection.username">sa</property> 
<property name="connection.password"></property> 


<!-- JDBC connection pool (use the built-in) --> 
<property name="connection.pool_size">1</property> 


<!-- SQL dialect --> 
<property name="dialect">org.hibernate.dialect.HSQLDiale 
ct</property> 


<!-- Enable Hibernate's automatic session context manage 
ment --> 

<property name="current_session_context_class">thread</p 
roperty> 

<!-- Disable the second-level cache --> 

<property name="cache.provider_class">org.hibernate.cach 
e.NoCacheProvider</property> 


<!-- Echo all executed SQL to stdout --> 
<property name="Show_sql">true</property> 


<!-- Drop and re-create the database schema on startup - 
<property name="hbm2dd1.auto">create</property> 
<mapping resource="events/Event.hbm.xm1"/> 
</session-factory> 
</hibernate-configuration> 
注意 这 个 XML 配置 使 用 了 一 个 不 同 的 DTD。 在 这 里 ， 我 们 配置 了 Hibernate 
的 SessionFactory 一 一 个 关联 于 特定 数据 库 全 局 的 工厂 (factory) 。 如 果 你 要 


使 用 多 个 数据 库 ， 就 要 用 多 个 的 &lt;session-factory&gt; ， 通 常 把 它们 放 在 多 
个 配置 文件 中 (为 了 更 容 萄 启动 ) 。 


最 开始 的 4 个 property 元 素 包 含 必 要 的 JDBC 连 接 信 息 。 方 言 (dialect ) 

的 property 元 素 指 明 Hibernate 生成 的 特定 SQL 变量。 你 很 快 会 看 到 ，Hibernate 

对 持久 化 上 下 文 的 自动 Session 管理 就 会 派 上 用 场 。 打开 hbm2ddl.auto 选项 将 自 

动 生 成 数据 库 模式 (schema) 一 直接 加 入 数据 库 中 。 当 然 这 个 选项 也 可 以 被 关闭 
(通过 去 除 这 个 配置 选项 ) 或 者 通过 Ant 任 务 SchemaExport 的 帮助 来 把 数据 库 

schema 重 定向 到 文件 中 。 最 后 ， 在 配置 中 为 持久 化 类 加 入 映射 文件 。 


把 这 个 文件 拷贝 到 源 代码 目录 下 面 ， 这 样 它 就 位 于 classpath 的 根 目 录 的 最 后 。 
Hibernate 在 启动 时 会 自动 在 classpath 的 根 目录 查找 名 为 hibernate.cfg.xml 的 
配置 文件 。 


1.2.4. 用 Ant 构 建 


现在 我 们 用 Ant 来 构建 应 用 程序 。 你 必须 先 安装 Ant 一 可 以 从 Ant 下 载 页 面 得 到 它 。 
怎样 安装 Ant 就 不 在 这 里 介绍 了 ， 请 参考 Ant 用 户 手册 。 当 你 安装 完了 Ant， 就 可 以 
开始 创建 build.xml 文件 ， 把 它 直 接 放 在 开发 目录 下 面 。 


一 个 简单 的 build 文 件 看 起 来 像 这 样 : 


<project name="hibernate-tutorial" default="compile"> 


<property name="Sourcedir" value="${basedir}/src"/> 
<property name="targetdir" value="${basedir}/bin"/> 
<property name="librarydir" value="${basedir}/lib"/> 


<path id="libraries"> 
<fileset dir="${librarydir}"> 
<include name="*.jar"/> 
</fileset> 
</path> 


<target name="clean"> 
<delete dir="${targetdir}"/> 
<mkdir dir="${targetdir}"/> 
</target> 


<target name="compile" depends="clean, copy-resources"> 
<javac srcdir="${sourcedir }" 
destdir="${targetdir}" 
classpathref="libraries"/> 
</target> 


<target name="copy-resources"> 
<copy todir="${targetdir}"> 
<fileset dir="${sourcedir}"> 
<exclude name="**/*,.java"/> 


</fileset> 
</copy> 
</target> 
</project> 
这 将 告诉 Ant 把 所 有 在 lib 目 录 下 以 .jar 结尾 的 文件 拷贝 到 classpath 中 以 供 编译 之 
用 。 它 也 把 所 有 的 非 Java 源 代码 文件 ， 例 如 配置 和 Hibernate 了 映射 文件 ， 找 贝 到 目 


标 目录 。 如 果 你 现在 运行 Ant， 会 得 到 以 下 输出 : 


C:\hibernateTutorial\>ant 
Buildfile: build.xml 


copy-resources: 
[copy] Copying 2 files to C:\hibernateTutorial\bin 


compile: 
[javac] Compiling 1 source file to C:\hibernateTutorial\bin 


BUILD SUCCESSFUL 
Total time: 1 second 


1.2.5. 启动 和 辅助 类 


是 时 候 来 加 载 和 储存 一 些 Event 对 象 了 ， 但 首先 我 们 得 编写 一 些 基础 的 代码 以 完 
成 设置 。 我 们 必须 启动 Hibernate， 此 过 程 包 括 创建 一 个 全 局 

的 SessoinFactory ， 并 把 它 储存 在 应 用 程序 代码 容易 访问 的 地 

方 。 SessionFactory 可 以 创建 并 打开 新 的 Session 。 一 个 Session 代表 一 个 
单线 程 的 单元 操作 ， SessionFactory 则 是 个 线程 安全 的 全 局 对 象 ， 只 需要 被 实 

例 化 一 次 。 


我 们 将 创建 一 个 HibernateUtil 辅助 类 (helper class) 来 负责 启动 Hibernate 和 
更 方便 地 操作 SessionFactory 。 让 我 们 来 看 一 下 它 的 实现 : 


package util; 


import org.hibernate.*; 
import org.hibernate.cfg.*; 


public class HibernateUtil { 
private static final SessionFactory sessionFactory; 


static { 
try { 
// Create the SessionFactory from hibernate.cfg.xml 
sessionFactory = new Configuration().configure().bui 
ldSessionFactory(); 
} catch (Throwable ex) { 
// Make sure you log the exception, as it might be s 
wallowed 
System.err.printin("Initial SessionFactory creation 
failed." + ex); 
throw new ExceptionInInitializerError(ex); 
} 


} 


public static SessionFactory getSessionFactory() { 
return sessionFactory; 


} 


这 个 类 不 但 在 它 的 静态 初始 化 过 程 ( 仅 当 加 载 这 个 类 的 时 候 被 JVM 执 行 一 次 ) 中 产 
生 全 局 的 SessionFactory ， 而 且 隐 茂 了 它 使 用 了 静态 singleton 的 事实 。 它 也 可 
能 在 应 用 程序 服务 器 中 的 JNDI 查 找 SessionFactory ° 


如 果 你 在 配置 文件 中 给 SessionFactory 一 个 名 字 ， 在 SessionFactory 创建 
后 ，Hibernate 会 试 着 把 它 绑 定 到 JNDI。 要 完全 避免 这 样 的 代码 ， 你 也 可 以 使 用 
JMX 部 署 ， 让 具有 JMX 能 力 的 容器 来 实例 化 HibernateService 并 把 它 绑 定 到 
JNDI。 这 些 高 级 可 选项 在 后 面 的 章节 中 会 讨论 到 。 


把 HibernateUtil.java 放 在 开发 目录 的 源 代码 路 径 下 ， 与 放 events 的 包 并 
列 : 


+lib 
<Hibernate and third-party libraries> 
+Src 
+events 
Event.java 
Event .hbm. xml 
+util 
HibernateUtil. java 
hibernate.cfg.xml 
+data 
build.xml 


再 次 编译 这 个 应 用 程序 应 该 不 会 有 问题 。 最 后 我 们 需要 配置 一 个 日 志 (logging) 系 
统 一 Hibernate 使 用 通用 日 志 接 口 ， 允 许 你 在 Log4j 和 JDK 1.4 日 志 之 间 进 行 选择 。 
多 数 开 发 者 更 喜欢 Log4j : 从 Hibernate 的 发 布 包 中 (CH etc/ 目录 下 ) # 

贝 log4j.properties 到 你 的 src 目录 ， 与 hibernate.cfg.xml . 放 在 一 起 。 
看 一 下 配置 示例 ， 如 果 你 希望 看 到 更 加 详细 的 输出 信息 ， 你 可 以 修改 配置 。 默 认 情 
况 下 ， 只 有 Hibernate 的 启动 信息 才 会 显示 在 标准 输出 上 。 


示例 的 基本 框架 完成 了 一 现在 我 们 可 以 用 Hibernate 来 做 些 申 正 的 工作 。 


1.2.6. 加 载 并 存储 对 象 


我 们 终于 可 以 使 用 Hibernate 来 加 载 和 存储 对 象 了 ， 编 写 一 个 带 有 main() 方法 
的 EventManager 类 : 


package events; 
import org.hibernate.Session; 


import java.util.Date; 
import util.HibernateUtil; 
public class EventManager { 


public static void main(String[] args) { 
EventManager mgr = new EventManager(); 


if (args[0].equals("store")) { 


mgr .createAndStoreEvent("My Event", new Date()); 
} 


HibernateUtil.getSessionFactory().close(); 


} 


private void createAndStoreEvent(String title, Date theDate) 
Session session = HibernateUtil.getSessionFactory().getc 
urrentSession(); 
session. beginTransaction(); 
Event theEvent = new Event(); 
theEvent.setTitle(title); 
theEvent.setDate(theDate) ; 


session.save(theEvent); 


session.getTransaction().commit(); 


我 们 创建 了 个 新 的 Event 对 象 并 把 它 传递 给 Hibernate。 现 在 Hibernate 负 责 与 
SQL 打交道 ， 并 把 INSERT 命令 传 给 数据 库 。 在 运行 之 前 ， 让 我 们 看 一 下 处 
理 Session 和 Transaction 的 代码 。 


一 个 Session 就 是 个 单一 的 工作 单元 。 我 们 暂时 让 事情 简单 一 些 ， 并 假设 
Hibernate Session 和 数据 库 事务 是 一 一 对 应 的 。 为 了 让 我 们 的 代码 从 底层 的 事务 
系统 中 脱离 出 来 (此 例 中 是 JDBC， 但 也 可 能 是 JTA) ， 我 们 使 用 Hibernate 
Session 中 的 Transaction API ° 


sessionFactory.getCurrentSession() 是 干什么 的 呢 ? 首先 ， 只 要 你 持 
有 SessionFactory (幸亏 我 们 有 HibernateUtil ， 可 以 随时 获得 ) ， 大 可 在 
任何 时 候 、 任 何 地 点 调用 这 个 方法 。 getCurrentSession() 方法 总 会 返回 “当前 
的 "工作 单元 。 记 得 我 们 在 hibernate.cfg.xml 中 把 这 一 配置 选项 调整 
为 "thread" 了 吗 ? 因此 ， 因 此 ， 当 前 工作 单元 被 绑 定 到 当前 执行 我 们 应 用 程序 的 
Java 线 程 。 但 是 ， 这 并 非 是 完全 准确 的 ,你 还 得 考虑 工作 单元 的 生命 周期 范围 
(scope), 它 何 时 开始 ,又 何 时 结 


Session 在 第 一 次 被 使 用 的 时 候 , 即 第 一 次 调用 getCurrentSession() 的 时 候 ， 
其 生命 周期 就 开始 。 然 后 它 被 Hibernate 绑 定 到 当前 线程 。 当 事务 结束 的 时 候 ， 不 管 
是 提交 还 是 回 滚 ，Hibernate 会 自动 把 Session 从 当前 线程 剥离 ， 并 且 关 闭 它 。 假 
若 你 再 次 调用 getCurrentSession() ， 你 会 得 到 一 个 新 的 Session ， 并 且 开 始 
一 个 新 的 工作 单元 。 这 种 线程 绑 定 (thread-bound) 的 编程 模型 (model) 是 使 用 
Hibernate 的 最 广泛 的 方式 ,因为 它 支持 对 你 的 代码 灵活 分 层 (事务 划分 可 以 和 你 的 数 
据 访 问 代码 分 离开 来 ,在 本 教程 的 后 面部 分 就 会 这 么 做 ) 。 


和 工作 单元 的 生命 周期 这 个 话题 相关 ，Hibernate Session 是 否 被 应 该 用 来 执行 
多 次 数据 库 操作 ?了 上面 的 例子 对 每 一 次 操作 使 用 了 一 个 Session ， 这 完全 是 巧 

合 ， 这 个 例子 不 是 很 复杂 ， 无 法 展示 其 他 方式 。Hibernate Session 的 生命 周期 
可 以 很 灵活 ， 但 是 你 绝 不 要 把 你 的 应 用 程序 设计 成 为 每 一 次 数据 库 操作 都 用 一 个 新 
的 Hibernate Session 。 因 此 就 算 下 面 的 例子 (它们 都 很 简单 ) 中 你 可 以 看 到 这 
种 用 法 ， 记 住 每 次 操作 一 个 Session 是 一 个 反 模 式 。 在 本 教程 的 后 面 会 展示 一 个 真正 
的 (web) 程 序 。 


关于 事务 处 理 及 事务 边界 界定 的 详细 信息 ， 请 参看 第 11 章 事务 和 并 发 。 在 上 面 的 
例子 中 ， 我 们 也 忽略 了 所 有 的 错误 与 回 滚 的 处 理 。 


为 第 一 次 运行 我 们 的 程序 ， 我 们 得 在 Ant 的 build 文 件 中 增加 一 个 可 以 调用 得 到 的 
target ° 


<target name="run" depends="compile"> 
<java fork="true" classname="events.EventManager" classpathr 
ef="libraries"> 
<classpath path="${targetdir}"/> 
<arg value="${action}"/> 
</java> 
</target> 


action 参数 (argument) 的 值 是 通过 命令 行 调用 这 个 target 的 时 候 设 置 的 : 


C:\hibernateTutorial\>ant run -Daction=store 


你 应 该 会 看 到 ， 编 译 以 后 ，Hibernate 根 据 你 的 配置 启动 ， 并 产生 一 大 堆 的 输出 日 
志 。 在 日 志 最 后 你 会 看 到 下 面 这 行 


[java] Hibernate: insert into EVENTS (EVENT_DATE, title, EVENT_I 
D) values (?, ?, 7?) 


这 是 Hibernate 执 行 的 INSERT 命令 ， 问 号 代表 JDBC 的 绑 定 参数 。 如 果 想 要 看 到 乡 
E 或 者 减少 日 志 的 长 度 ， 就 要 调整 你 在 log4j.properties 文件 里 的 设 


我 们 想 要 列 出 所 有 已 经 被 存储 的 events， 就 要 增加 一 个 条 件 分 支 选 项 到 main 方 法 中 
去 。 
if (args[0].equals("store")) { 
mgr .createAndStoreEvent("My Event", new Date()); 
else if (args[0].equals("list")) { 
List events = mgr.listEvents(); 
for (int i = 0; i < events.size(); i++) { 
Event theEvent = (Event) events.get(i); 


System.out.printin("Event: " + theEvent.getTitle() + 
" Time: " + theEvent.getDate()); 


我 们 也 增加 一 个 新 的 listEvents() 方法 : 


private List listEvents() { 


Session session = HibernateUtil.getSessionFactory().getCurre 
ntSession(); 


session. beginTransaction(); 
List result = session.createQuery("from Event").list(); 
session.getTransaction().commit(); 


return result; 


我 们 在 这 里 是 用 一 个 HQL (Hibernate Query Language—Hibernate#i978 3 ) & 
询 语 句 来 从 数据 库 中 加 载 所 有 存在 的 Event 对 象 。Hibernate 会 生成 适当 的 SQL ， 
把 它 发 送 到 数据 库 ， 并 操作 从 查询 得 到 数据 的 Event 对 象 。 当 然 ， 你 可 以 使 用 
HQL 来 创建 更 加 复杂 的 查询 。 


现在 ， 根 据 以 下 步骤 来 执行 并 测试 以 上 各 项 : 


e 运行 ant run -Daction=store 来 保存 一 些 内 容 到 数据 库 。 当 然 ， 先 得 用 
hbm2ddl 来 生成 数据 库 Schema ° 


e 现在 把 hibernate.cfg.xml 文件 中 hbm2ddl 属 性 注释 掉 ， 这 样 我 们 就 取消 了 
在 启动 时 用 hbm2ddl 来 生成 数据 库 schema。 通 常 只 有 在 不 断 重复 进行 单元 测试 
的 时 候 才 需要 打开 它 ， 但 再 次 运行 hbbm2ddl 会 把 你 保存 的 一 切 都 删 掉 (drop ) 

create 配置 的 趴 实 含义 是 :“ 在 创建 SessionFactory 的 时 候 ， 从 schema 

中 drop 掉 所 有 的 表 ， 再 重新 创建 它们 ”。 


如 果 你 现在 使 用 命令 行 参 数 -Daction=list 运行 Ant， 你 会 看 到 那些 至 今 为 止 我 
们 所 储存 的 events。 当 然 ， 你 也 可 以 多 调用 几 次 store 以 保存 更 多 的 envents。 


注意 ， 很 多 Hibernate 新 手 在 这 一 步 会 失败 ， 我 们 不 时 看 到 关于 Table not found 错 误 
信息 的 提问 。 但 是 ， 只 要 你 根据 上 面 描述 的 步骤 来 执行 ， 就 不 会 有 这 个 问题 ， 因 为 
hbm2ddl 会 在 第 一 次 运行 的 时 候 创建 数据 库 schema， 后 继 的 应 用 程序 重 起 后 还 能 继 
续 使 用 这 个 schema。 假 若 你 修改 了 映射 ， 或 者 修改 了 数据 库 schema， 你 必须 把 
hbm2ddl 重 新 打开 一 次 。 





1.3. 第 二 部 分 一 关联 映射 


我 们 已 经 映射 了 一 个 持久 化 实体 类 到 表 上 。 让 我 们 在 这 个 基础 上 增加 一 些 类 之 间 的 
关联 。 首 先 我 们 往 应 用 程序 里 增加 人 (people) 的 概念 ， 并 存储 他 们 所 参与 的 一 个 
Event 列 表 。 ( 译 者 注 : 与 Event 一 样 ， 我 们 在 后 面 将 直接 使 用 person 来 表示 “人 ”而 
不 是 它 的 中 文 翻译 ) 


1.3.1. 1&4 Person Žž 
最 初 简单 的 Person 类 : 


package events; 
public class Person { 


private Long id; 
private int age; 
private String firstname; 
private String lastname; 


public Person() {} 


// Accessor methods for all properties, private setter for ' 
Id ' 


创建 一 个 名 为 Person.hbm.xml 的 新 映射 文件 ( 别 忘 了 最 上 面 的 DTD 引 用 ) 


<hibernate-mapping> 


<class name="events.Person" table="PERSON"> 
<id name="id" column="PERSON_ID"> 
<generator class="native"/> 
</id> 
<property name="age"/> 
<property name="firstname"/> 
<property name="lastname"/> 
</class> 


</hibernate-mapping> 


最 后 ， 把 新 的 映射 加 入 到 Hibernate 的 配置 中 : 


<mapping resource="events/Event.hbm. xm1"/> 
<mapping resource="events/Person.hbm. xm1"/> 


现在 我 们 在 这 两 个 实体 之 间 创 建 一 个 关联 。 显 然 ，persons 可 以 参与 一 系列 
events， 而 events 也 有 不 同 的 参加 者 (persons) 。 我 们 需要 处 理 的 设计 问题 是 关 
联 方向 (directionality) ， 阶 数 (multiplicity) 和 集合 (collection) 的 行为 。 
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1.3.2. 单 向 Set-based 的 关联 


我 们 将 向 Person 类 增加 一 连 串 的 events。 那 样 ， 通 过 调 

用 aPerson.getEvents() ， 就 可 以 轻松 地 导航 到 特定 person 所 参与 的 events， 而 
不 用 去 执行 一 个 显 式 的 查询 。 我 们 使 用 Java 的 集合 类 (collection) : set > AA 
set 不 包含 重复 的 元 素 及 与 我 们 无 关 的 排序 。 


我 们 需要 用 set 实现 一 个 单 向 多 值 关 联 。 让 我 们 在 Java 类 里 为 这 个 关联 编码 ， 接 着 
映射 它 : 


public class Person { 
private Set events = new HashSet(); 


public Set getEvents() { 
return events; 


} 


public void setEvents(Set events) { 
this.events = events; 


} 


在 映射 这 个 关联 之 前 ， 先 考虑 一 下 此 关联 的 另外 一 端 。 很 显然 ， 我 们 可 以 保持 这 个 
关联 是 单 向 的 。 或 者 ， 我 们 可 以 在 Event 里 创建 另外 一 个 集合 ， 如 果 希 望 能 够 双 
向 地 导航 ， 如 : anEvent.getParticipants() 。 从 功能 的 角度 来 说 ， 这 并 不 是 

必须 的 。 因 为 你 总 可 以 显 式 地 执行 一 个 查询 ， 以 获得 某 个 特定 event 的 所 有 参与 

者 。 这 是 个 在 设计 时 需要 做 出 的 选择 ， 完 全 由 你 来 决定 ， 但 此 讨论 中 关于 关联 的 阶 
数 是 清楚 的 : 即 两 端 都 是 “多 " 值 的 ， 我 们 把 它 叫 做 多 对 多 (many-io-1many) 关 联 。 因 
而 ， 我 们 使 用 Hibernate 的 多 对 多 映射 : 


<class name="events.Person" table="PERSON"> 
<id name="id" column="PERSON_ID"> 
<generator class="native"/> 
</id> 
<property name="age"/> 
<property name="firstname"/> 
<property name="lastname"/> 


<set name="events" table="PERSON_EVENT"> 

<key column="PERSON_ID"/> 

<many-to-many column="EVENT_ID" class="events.Event"/> 
</set> 


</class> 


Hibernate 支 持 各 种 各 样 的 集合 映射 ，&1lt;set&gt; 使 用 的 最 为 普遍 。 对 于 多 对 多 
关联 (或 叫 n:m 实 体 关 系 ) ,需要 一 个 关联 表 (association table) 。 A 里 面 的 每 
一 行 代表 从 person 到 event 的 一 个 关联 。 表 名 是 由 set 元 素 的 table 属性 配置 
的 。 关 联 里面 的 标识 符 字段 名 ， 对 于 person 的 一 端 ， 是 由 &lt;key&gt; 元 素 定 
义 ， 而 event 一 端的 字段 名 是 由 &lt;many-to-many&gt; 元 素 的 colum 属性 定 
义 。 你 也 必须 告诉 Hibernate 集 合 中 对 象 的 类 〈 也 就 是 位 于 这 个 集合 所 代表 的 关联 另 
外 一 端的 类 ) © 


而 这 个 映射 的 数据 库 Schema 有 是 : 











| | | 
| EVENTS | | PERSON_EVENT | | 














| 

| | | | | PERSON 
| 

| | | | | 
| 

| *EVENT_ID | <--> | “EVENT OED | | 
| 

| EVENT_DATE | | *PERSON_ID | <--> | *PERSON_ID 
| 

| TITLE | | | | AGE 
| 

| | | FIRSTNAME 





| LASTNAME 





1.3.3. 使 关联 工作 
我 们 把 一 些 people 和 events 一 起 放 到 EventManager 的 新 方法 中 : 


private void addPersonToEvent(Long personId, Long eventId) { 


Session session = HibernateUtil.getSessionFactory().getCurre 
ntSession(); 
session. beginTransaction(); 


Person aPerson = (Person) session.load(Person.class, personI 
d); 
Event anEvent = (Event) session.load(Event.class, eventId); 


aPerson.getEvents().add(anEvent); 


session.getTransaction().commit(); 


在 加 载 一 Person 和 Event 后 ， 使 用 普通 的 集合 方法 就 可 容 多 地 修改 我 们 定义 的 
集合 。 如 你 所 见 ， 没 有 显 式 的 update() 或 save() ，Hibernate 会 自动 检测 到 集 
合 已 经 被 修改 并 需要 更 新 回 数 据 库 。 这 叫做 自动 脏 检 查 (automatic dirty 
checking) ， 你 也 可 以 尝试 修改 任何 对 象 的 name 或 者 date 镶 性 ， 只 要 他 们 处 于 持久 
化 状态 ， 也 就 是 被 绑 定 到 某 个 Hibernate 的 Session 上 (如 :他 们 刚刚 在 一 个 单 
元 操作 被 加 载 或 者 保存 ) ，Hibernate 监 视 任何 改变 并 在 后 人 台 隐 式 写 的 方式 执行 
SQL。 同 步 内 存 状 态 和 数据 库 的 过 程 ， 通 常 只 在 单元 操作 结束 的 时 候 发 生 ， 称 此 过 
程 为 清理 缓存 (flushing) 。 在 我 们 的 代码 中 ， 工 作 单 元 由 数据 库 事务 的 提交 (或 
者 回 滚 ) KE 这 是 由 CurrentSessionContext 类 的 thread 配置 选项 定 
义 的 。 


当然 ， 你 也 可 以 在 不 同 的 单元 操作 里 面 加 载 person 和 event。 或 在 Session 以 外 修 
改 不 是 处 在 持久 化 (persistent) RA FMM R (REM RUA FAR AM > AB 
么 我 们 称 这 个 状态 为 脱 管 (detached) ) 。 你 甚至 可 以 在 一 个 集合 被 脱 管 时 修改 


~ 


已 : 





private void addPersonToEvent(Long personId，Long eventId) { 


Session session = HibernateUtil.getSessionFactory().getCurre 
ntSession(); 
session. beginTransaction(); 


Person aPerson = (Person) session 
.createQuery("select p from Person p left join fetch 
p.events where p.id = :pid") 
.setParameter("pid", personId) 
.uniqueResult(); // Eager fetch the collection so we 
can use it detached 


Event anEvent = (Event) session.load(Event.class, eventId); 
session.getTransaction().commit(); 
// End of first unit of work 


aPerson.getEvents().add(anEvent); // aPerson (and its collec 
tion) is detached 


// Begin second unit of work 


Session session2 = HibernateUtil.getSessionFactory().getCurr 
entSession(); 
session2.beginTransaction(); 


session2.update(aPerson); // Reattachment of aPerson 


session2.getTransaction().commit(); 


- update 的 调用 使 一 个 脱 管 对 象 重新 持久 化 ， 你 可 以 说 它 被 绑 定 到 一 个 新 的 单元 
操作 上 ， 剖 凡 在 脱 管状 态 下 对 它 所 做 的 任何 修改 都 会 被 保 请 到 数据 库 里 。 这 也 包括 
你 对 这 个 实体 对 象 的 集合 所 作 的 任何 改动 〈 增 加 /删除 ) 。 


这 对 我 们 当前 的 情形 不 是 很 有 用 ， 它 是 非常 重要 的 概念 你 可 以 把 它 融 入 到 你 自 
己 的 应 用 程序 设计 中 。 在 ee: 的 main 方 法 中 添加 一 个 新 的 动作 > 并 从 

命令 行 运行 它 练习 。 如 果 你 需要 person 及 event 的 标识 符 一 那 就 
用 save() 方法 反 È (你 可 能 需要 修改 前 面 的 一 些 方法 来 返回 那个 标识 符 ) 


else if (args[0].equals("addpersontoevent")) { 
Long eventId = mgr.createAndStoreEvent("My Event", new Date( 
) ) ; 


Long personId = mgr.createAndStorePerson("Foo", "Bar"); 

mgr .addPersonToEvent(personiId, eventId); 

System.out.println("Added person " + personId + " to event " 
+ eventId); 


} 


上 面 是 个 关于 两 个 同等 重要 的 实体 类 间 关 联 的 例子 。 像 前 面 所 提 到 的 那样 ， 在 特定 
的 模型 中 也 存在 其 它 的 类 和 类 型 ， 这 些 类 和 类 型 通常 是 “次 要 的 ”。 你 已 看 到 过 其 中 
的 一 些 ， 像 int 或 String 。 我 们 称 这 些 类 为 值 类 型 〈value type) ， 它 们 的 实 
例 依 赖 (depend) 在 某 个 特定 的 实体 上 。 这 些 类 型 的 实例 没有 它们 自己 的 标识 
(identity) ， 也 不 能 在 实体 间 被 共享 (比如 ， 两 个 person 不 能 引用 同一 

个 firstname 对 象 ， 即 使 他 们 有 相同 的 first name) 。 当 然 ， 值 类 型 并 不 仅仅 在 
JDK 中 存在 (事实 上 ， 在 一 个 Hibernate 应 用 程序 中 ， 所 有 的 JDK 类 都 被 视 为 值 类 
Al) ， 而 且 你 也 可 以 编写 你 自己 的 依赖 类 ， 例 如 Address > MonetaryAmount ° 


你 也 可 以 设计 一 个 值 类 型 的 集合 ， 这 在 概念 上 与 引用 其 它 实体 的 集合 有 很 大 的 不 
同 ， 但 是 在 Java 里 面 看 起 来 几乎 是 一 样 的 。 


1.3.4. 值 类 型 的 集合 


我 们 把 一 个 值 类 型 对 象 的 集合 加 入 Person 实体 中 。 我 们 硕 望 保存 email 地 址 ， 所 
以 使 用 String 类 型 ， 而 且 这 次 的 集合 类 型 又 是 Set 


private Set emailAddresses = new HashSet(); 


public Set getEmailAddresses() { 
return emailAddresses; 


} 


public void setEmailAddresses(Set emailAddresses) { 
this.emailAddresses = emailAddresses; 


} 


这 个 Set 的 映射 


<set name="emailAddresses" table="PERSON_EMAIL_ADDR"> 
<key column="PERSON_ID"/> 
<element type="string" column="EMAIL_ADDR"/> 
</set> 


比较 这 次 和 此 前 映射 的 差别 ， 主 要 在 于 element 部 分 ， 这 次 并 没有 包含 对 其 它 实 
体 引用 的 集合 ， 而 是 元 素 类 型 为 String HES (在 映射 中 使 用 小 写 的 名 

字 ?”string "是 向 你 表明 它 是 一 个 Hibernate 的 映射 类 型 或 者 类 型 转换 器 ) 。 和 之 前 一 

样 ， set 元 素 的 table 属性 决定 了 用 于 集合 的 表 名 。 key 元 素 定 义 了 在 集合 表 
中 外 键 的 字段 名 。 element 元 素 的 column 属性 定义 用 于 实际 保存 string 值 的 
字段 名 。 


看 一 下 修改 后 的 数据 库 schema。 











| EVENTS | | PERSON_EVENT | | | 


























| | | | | PERSON | 
| | 

| | | | | | 
| PERSON_EMAIL_ADDR | 

| *EVENT_ID | <--> | *EVENT_ID | | | 
| | 

| EVENT_DATE | | *PERSON_ID | <--> | *PERSON_ID | 
<--> | *PERSON_ID | 

| | | | | AGE | 
| *EMAIL_ADDR | 

| | | FIRSTNAME | 
| | 

| LASTNAME | 





你 可 以 看 到 集合 表 的 主键 实际 上 是 个 复合 主键 ， 同 时 使 用 了 2 个 字段 。 这 也 暗示 了 
对 于 同一 个 person 不 能 有 重复 的 email 地 址 ， 这 正 是 Java 里 面 使 用 Set 时 候 所 需要 的 
语义 (Set 里 元 素 不 能 重复 ) 。 


你 现在 可 以 试 着 把 元 素 加 入 到 这 个 集合 ， 就 像 我 们 在 之 前 关联 person 和 event 的 那 
样 。 其 实现 的 Java 代 码 是 相同 的 : 


private void addEmailToPerson(Long personId，String emailAddress 


av 


Session session = HibernateUtil.getSessionFactory().getCurre 
ntSession(); 
session. beginTransaction(); 


Person aPerson = (Person) session.load(Person.class, personI 
d); 


// The getEmailAddresses() might trigger a lazy load of the 
collection 
aPerson.getEmailAddresses().add(emailAddress) ; 


session.getTransaction().commit(); 


这 次 我 们 没有 使 用 fetch 查 询 来 初始 化 集合 。 因 此 ， 调 用 其 getter 方 法 会 触发 另 一 附 
加 的 select 来 初始 化 集合 ， 这 样 我 们 才能 把 元 素 添 加 进去 。 检 查 SQL log， 试 着 通过 
预先 抓 取 来 优化 它 。 
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1.3.5. 双向 关联 


接 下 来 我 们 将 映射 双向 关联 (bi-directional association) 一 在 Java 里 让 person 和 
event 可 以 从 关联 的 任何 一 端 访问 另 一 端 ? 当然 ， 数 据 库 schema 没 有 改变 ， 我 们 仍 
然 需 要 多 对 多 的 阶 数 。 一 个 关系 型 数据 库 要 比 网 络 编程 语言 更 加 灵活 ， 所 以 它 并 不 
需要 任何 像 导 航 方向 (navigation direction) 的 东西 一 数据 可 以 用 任何 可 能 的 方式 
进行 查看 和 获取 。 


首先 ， 把 一 个 参与 者 (person) 的 集合 加 入 Event AP: 


private Set participants = new HashSet(); 


public Set getParticipants() { 
return participants; 
} 


public void setParticipants(Set participants) { 
this.participants = participants; 


} 


在 Event.hbm.xml 里 面 也 映射 这 个 关联 。 


<Set name="participants" table="PERSON_EVENT" inverse="true"> 
<key column="EVENT_ID"/> 
<many-to-many column="PERSON_ID" class="events.Person"/> 
</set> 


如 你 所 见 ， 两 个 映射 文件 里 都 有 普通 的 set 映射 。 注 意 在 两 个 映射 文件 中 ， 互 换 
了 key 和 many-to-many 的 字段 名 。 这 里 最 重要 的 是 Event 映射 文件 里 增加 
了 set 元 素 的 inverse="true" 属性 。 


这 意味 着 在 需要 的 时 候 ，Hibernate 能 在 关联 的 另 一 端 一 person 类 得 到 两 个 实体 
间 关 联 的 信息 。 这 将 会 极 大 地 帮助 你 理解 双向 关联 是 如 何在 两 个 实体 问 被 创建 的 。 


1.3.6. 使 双向 连 起 来 


首先 请 记 住 ，Hibernate 并 不 影响 通常 的 Java 语 义 。 在 单 向 关联 的 例子 中 ， 我 们 是 
怎样 在 Person 和 Event 之 问 创建 联系 的 ?了 我们 把 Event 实例 添加 

到 Person 实例 内 的 event 引 用 集合 里 。 因 此 很 显然 ， 如 果 我 们 要 让 这 个 关联 可 以 
双向 地 工作 ， 我 们 需要 在 另外 一 端 做 同样 的 事情 一 把 Person 实例 加 

A Event 类 内 的 Person 引 用 集合 。 这 “在 关联 的 两 端 设置 联系 ”是 完全 必要 的 而 且 
你 都 得 这 么 做 。 


许多 开发 人 员 防 御 式 地 编程 ， 创 建 管理 关联 的 方法 来 保证 正确 的 设置 了 关联 的 两 
端 ， 比 如 在 Person 里 : 


protected Set getEvents() { 
return events; 
} 


protected void setEvents(Set events) { 
this.events = events; 


} 


public void addToEvent(Event event) { 
this.getEvents().add(event); 
event.getParticipants().add(this); 


} 


public void removeFromEvent(Event event) { 
this.getEvents().remove(event); 
event.getParticipants().remove(this); 


注意 现在 对 于 集合 的 get 和 set 方 法 的 访问 级 别 是 protected - 这 允许 在 位 于 同一 个 包 

(package) 中 的 类 以 及 继承 自 这 个 类 的 子 类 可 以 访问 这 些 方法 ， 但 禁止 其 他 任何 
人 的 直接 访问 ， 避 免 了 集合 内 容 的 混乱 。 你 应 尽 可 能 地 在 另 一 端 也 把 集合 的 访问 级 
别 设 成 protected ° 


inverse 映射 属性 究竟 表示 什么 呢 ? 对 于 你 和 Java 来 说 ， 一 个 双向 关联 仅仅 是 在 
两 端 简单 地 正确 设置 引用 。 然 而 ，Hibernate 并 没有 足够 的 信息 去 正确 地 执 
行 INSERT 和 UPDATE 语句 (以 避免 违反 数据 库 约束 ) ， 所 以 它 需要 一 些 帮助 来 
正确 的 处 理 双向 关联 。 把 关联 的 一 端 设置 为 inverse 将 告诉 Hibernate 忽 略 关 联 的 
这 一 端 ， 把 这 端 看 成 是 另外 一 端的 一 个 镜 象 (miror) 。 这 就 是 所 需 的 全 部 信息 ， 
Hibernate 利 用 这 些 信 息 来 处 理 把 一 个 有 向 导航 模型 转移 到 数据 库 sSchema 时 的 所 有 
问题 。 你 只 需要 记 住 这 个 直观 的 规则 : 所 有 的 双向 关联 需要 有 一 端 被 设置 
为 inverse 。 在 一 对 多 关联 中 它 必 须 是 代表 多 (many) 的 那 端 。 而 在 多 对 多 
(many-to-many) 关联 中 ， 你 可 以 任意 选取 一 端 ， 因 为 两 端 之 问 并 没有 差别 。 


让 我 们 把 进入 一 个 小 型 的 web 应 用 程序 i 
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1.4. 第 三 部 分 - EventManager web 应 用 程序 


Hibernate web 应 用 程序 使 用 Session 和 Transaction 的 方式 几乎 和 独立 应 用 
程序 是 一 样 的 。 但 是 ， 有 一 些 常见 的 模式 (pattern) 非常 有 用 。 现 在 我 们 编写 一 
个 EventManagerServlet 。 这 个 servlet 可 以 列 出 数据 库 中 保存 的 所 有 的 events ， 
还 提供 一 个 HTML 表 单 来 增加 新 的 events 。 


1.4.1. 编写 基本 的 Servlet 
在 你 的 源 代 码 目 录 的 events 包 中 创建 一 个 新 的 类 : 


package events; 
// Imports 
public class EventManagerServlet extends HttpServlet { 


// Servlet code 


我 们 后 面 会 用 到 dateFormatter 的 工具 ， 它 把 Date 对 象 转换 为 字符 串 。 只 要 
一 个 formatter 作 为 servlet 的 成 员 就 可 以 了 。 


这 个 servlet 只 处 理 HTTP GET 请 求 ， 因 此 ， 我 们 要 实现 的 是 doGet() FH: 


protected void doGet(HttpServletRequest request, 
HttpServletResponse response) 
throws ServletException, IOException { 


SimpleDateFormat dateFormatter = new SimpleDateFormat("dd.MM 
-yyyy"); 


try { 
// Begin unit of work 


HibernateUtil.getSessionFactory( ) 
.getCurrentSession().beginTransaction(); 


// Process request and render page... 
// End unit of work 
HibernateUtil.getSessionFactory( ) 
.getCurrentSession().getTransaction().commit(); 
} catch (Exception ex) { 
HibernateUtil.getSessionFactory() 
.getCurrentSession().getTransaction().rollback() 


throw new ServletException(ex); 


我 们 称 这 里 应 用 的 模式 为 每 次 请 求 一 个 session(session-per-request)。 当 有 请 求 到 
达 这 个 servlet 的 时 候 ， 通 过 对 SessionFactory 的 第 一 次 调用 ， 打 开 一 个 新 的 
Hibernate Session 。 然 后 启动 一 个 数据 库 事务 一 所 有 的 数据 访问 都 是 在 事务 中 
进行 ， 不 管 是 读 还 是 写 ( 我 们 在 应 用 程序 中 不 使 用 auto-commit 模 式 ) 。 


不 要 为 每 次 数据 库 操作 都 使 用 一 个 新 的 Hibernate Session 。 将 Hibernate 
Session 的 范围 设置 为 整个 请 求 。 要 用 getCurrentSession() ， 这 样 它 自动 会 
绑 定 到 当前 Java 线 程 。 


下 一 步 ， 对 请 求 的 可 能 动作 进行 处 理 ， 泻 染 出 反馈 的 HTML 。 我 们 很 快 就 会 涉及 到 
那 部 分 。 


最 后 ， 当 处 理 与 泻 染 都 结束 的 时 候 ， 这 个 工作 单元 就 结束 了 。 假 若 在 处 理 或 泻 染 的 
时 候 有 任何 错误 发 生 ， 会 抛 出 一 个 异常 ， 回 滚 数据 库 事 务 。 这 

> session-per-request 模式 就 完成 了 。 为 了 避免 在 每 个 servlet 中 都 编写 事务 
边界 界定 的 代码 ， 可 以 考虑 写 一 个 Servlet 过 滤器 (filter) 来 更 好 地 解决 。 关 于 这 一 
模式 的 更 多 信息 ， 请 参阅 Hibernate 网 站 和 Wiki， 这 一 模式 叫做 Open Session in 
View 一 只 要 你 考虑 用 JSP 来 泻 染 你 的 视图 (view) ， 而 不 是 在 servlet 中 ， 你 就 会 很 
快 用 到 它 。 


1.4.2. 处 理 与 泻 染 
我 们 来 实现 处 理 请 求 以 及 演 染 页 面 的 工作 。 


// Write HTML header 
Printwriter out = response.getWriter(); 
out.printin("<html><head><title>Event Manager</title></head><bod 


y>"); 


// Handle actions 
if ( "store".equals(request.getParameter("action")) ) { 


String eventTitle = request.getParameter("eventTitle"); 
String eventDate = request.getParameter("eventDate"); 


if ( "".equals(eventTitle) || "".equals(eventDate) ) { 
out.println("<b><i>Please enter event title and date.</i 
></b>"); 
} else { 


createAndStoreEvent(eventTitle, dateFormatter.parse(even 
tDate)); 
out.println("<b><i>Added event.</i></b>"); 
} 


} 


// Print page 
printEventForm(out); 
listEvents(out, dateFormatter); 


// Write HTML footer 

out .println("</body></html>"); 
out.flush(); 

out.close(); 


listEvents() 方法 使 用 绑 定 到 当前 线程 的 Hibernate Session 来 执行 查询 : 


private void listEvents(PrintWriter out, SimpleDateFormat dateFo 
rmatter) { 


List result = HibernateUtil.getSessionFactory() 
.getCurrentSession().createCriteria(Event.cl 
ass).list(); 
if (result.size() > 0) { 
out.printin("<h2>Events in database:</h2>"); 
out.printin("<table border='1'>"); 
out.println("<tr>"); 
out.printin("<th>Event title</th>"); 
out.printin("<th>Event date</th>"); 
out.println("</tr>"); 
for (Iterator it = result.iterator(); it.hasNext();) { 
Event event = (Event) it.next(); 
out.println("<tr>"); 
out.println("<td>" + event.getTitle() + "</td>"); 
out.println("<td>" + dateFormatter.format(event.getD 
ate()) + "</td>"); 
out.printlin("</tr>"); 
} 


out.println("</table>"); 


最 后 ， store 动作 会 被 导向 到 createAndStoreEvent() 方法 ， 它 也 使 用 当前 线 
程 的 Session : 


protected void createAndStoreEvent(String title, Date theDate) { 
Event theEvent = new Event(); 
theEvent .setTitle(title) ; 
theEvent.setDate(theDate) ; 


HibernateUtil.getSessionFactory( ) 
.getCurrentSession().save(theEvent); 


大 功 告 成 ， 这 个 servlet 写 完了 。Hibernate 会 在 单一 的 Session 

和 Transaction 中 处 理 到 达 的 servlet 请 求 。 如 同 在 前 面 的 独立 应 用 程序 中 那样 ， 
Hibernate 可 以 自动 的 把 这 些 对 象 绑 定 到 当前 运行 的 线程 中 。 这 给 了 你 用 任何 你 喜欢 
的 方式 来 对 代码 分 层 及 访问 SessionFactory 的 自由 。 通 常 ， 你 会 用 更 加 完备 的 
设计 ， 把 数据 访问 代码 转移 到 数据 访问 对 象 中 (DAO 模 式 ) 。 请 参见 Hibernate 
Wiki， 那 里 有 更 多 的 例子 。 


1.4.3. 部 署 与 测试 


要 发 布 这 个 程序 ， 你 得 把 它 打 成 Web 发 布 包 : WAR 文 件 。 把 下 面 的 脚本 加 入 到 你 
的 build.xml 中 : 


<target name="war" depends="compile"> 
<war destfile="hibernate-tutorial.war" webxml="web.xmLl"> 
<lib dir="${librarydir}"> 
<exclude name="jsdk*.jar"/> 
</lib> 


<classes dir="${targetdir}"/> 
</war> 
</target> 


这 段 代码 在 你 的 开发 目录 中 创建 一 个 hibernate-tutorial.war 的 文件 。 它 把 所 
有 的 类 库 和 web.xml 描述 文件 都 打包 进去 ，web.xml 文件 应 该 位 于 你 的 开发 根 目 
录 中 : 


<?xml version="1.0" encoding="UTF-8"?> 

<web-app version="2.4" 
xmlns="http://java.sun.com/xml/ns/j2ee" 
xmins:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xSi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://j 

ava.sun.com/xml/ns/j2ee/web-app_2 4.xsd"> 


<servlet> 
<servlet-name>Event Manager</servlet-name> 
<servlet-class>events.EventManagerServlet</servlet-class 


</servlet> 


<servlet -mapping> 
<servlet-name>Event Manager</servlet-name> 
<url-pattern>/eventmanager</url-pattern> 
</servlet -mapping> 
</web-app> 


请 注意 在 你 编译 和 部 署 web 应 用 程 之 前 ， 需 要 一 个 附加 的 类 库 : jsdk.jar 。 这 是 
Java Servlet 开 发 包 ， 假 若 你 还 没有 ， 可 以 从 Sun 网 站 上 下 载 ， 把 它 copy 到 你 的 lib 目 
录 。 但 是 ， 它 仅仅 是 在 编译 时 需要 ， 不 会 被 打 入 WAR 包 。 


在 你 的 开发 目录 中 ， 调 用 ant war 来 构建 、 打 包 ， 然 后 

把 hibernate-tutorial.war 文件 拷贝 到 你 的 tomcat 的 webapps 目录 下 。 假 若 
尔 还 没 安装 Tomcat， 就 去 下 载 一 个 ， 按 照 指 南 来 安装 。 对 此 应 用 的 发 布 ， 你 不 需要 
修改 任何 Tomcat 的 配置 。 


在 部 署 完 ， 局 动 Tomcat 之 后 ， 通 

过 http://localhost :8080/hibernate-tutorial/eventmanager 进行 访问 你 的 
应 用 ， 在 第 一 次 servlet 请 求 发 生 时 ， 请 在 Tomcat log 中 确认 你 看 到 Hibernate 被 初始 
化 了 ( HibernateUtil 的 静态 初始 化 器 被 调用 ) ， 假 若 有 任何 异常 抛 出 ， 也 可 以 


看 到 详细 的 输出 。 


本 章 履 盖 了 如 何 编写 一 个 简单 独立 的 Hibernate 命 令 行 应 用 程序 及 小 型 的 Hibernate 

web 应 用 程序 的 基本 要 素 。 

如 果 你 已 经 对 Hibernate 感 到 自信 ， 通 过 开发 指南 目录 ， 继 续 浏 览 你 感 兴趣 的 内 容 一 
那些 会 被 问 到 的 问题 大 多 是 事务 处 理 (第 11 章 事务 和 并 发 )， 抓 取 (fetch) 的 效率 
(第 19 章 提升 性 能 )， 或 者 API 的 使 用 (第 10 章 与 对 象 共事 ) 和 查询 的 特性 (第 10.4 
节 “查询 ") 。 


别 忘 了 去 Hibernate 的 网 站 查看 更 多 (有 针对 性 的 ) 示例 。 


第 2 章 体系 结构 (Architecture) 


e 2.1. 概况 (Overview) 

e 2.2. 实例 状态 

e 2.3. JMX 整 合 

© 2.4. 对 JCA 的 支持 

e 2.5. 上 下 文 相关 的 (Contextual) Session 


2.1. 概况 (Overview) 


一 个 非常 简要 的 Hibernate 体 系 结构 的 概要 图 : 
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从 这 个 图 可 以 看 出 ，Hibernate 使 用 数据 库 和 配置 信息 来 为 应 用 程序 提供 持久 化 服务 
(以 及 持久 的 对 象 ) © 


我 们 来 更 详细 地 看 一 下 Hibernate 运 行 时 体系 结构 。 由 于 Hibernate 非 常 灵 活 ， 且 支 
持 多 种 应 用 方案 ， 所 以 我 们 这 只 描述 一 下 两 种 极端 的 情况 。"“ 轻 型 "的 体系 结构 方 
案 ， 要 求 应 用 程序 提供 自己 的 JDBC 连接 并 管理 自己 的 事务 。 这 种 方案 使 用 了 
Hibernate API 的 最 小 子 集 : 


Transient Objects | Application 
. Persistent 
| Objects 
SessionFactory Session JDBC JNDI | JTA 


Database 


“全 面 解决 "的 体系 结构 方案 ， 将 应 用 层 从 底层 的 JDBC/JTA API 中 抽象 出 来 ， 而 让 
Hibernate 来 处 理 这 些 细节 。 


Transient Objects | Application 
Persistent 
Objects 
SessionFactory 


Session Transaction 
TransactionFactory ConnectionProvider 


JNDI JDBC JTA 


Database 


图 中 各 个 对 象 的 定义 如 下 : 
SessionFactory ( org.hibernate.SessionFactory ) 


针对 单个 数据 库 映射 关系 经 过 编译 后 的 内 存 镜 像 ， 是 线程 安全 的 〈 不 可 变 ) 。 它 是 
生成 Session 的 工厂 ， 本 身 要 用 到 ConnectionProvider 。 该 对 象 可 以 在 进程 
或 集群 的 级 别 上 ， 为 那些 事务 之 问 可 以 重用 的 数据 提供 可 选 的 二 级 缓存 。 
Session ( org.hibernate.Session ) 


表示 应 用 程序 与 持久 储存 层 之 间 交 互 操 作 的 一 个 单线 程 对 象 ， 此 对 象 生 存 期 很 短 。 
其 隐藏 了 JDBC 连 接 ， igs Transaction 的 工厂 。 其 会 持 有 一 个 针对 持久 化 对 象 


的 必 选 (第 一 级 ) 缓存 ， 在 遍历 对 象 图 或 者 根据 持久 化 标识 查找 对 象 时 会 用 到 。 
持久 的 对 象 及 其 集合 


带 有 持久 化 状态 的 、 具 有 业务 功能 的 单线 程 对 象 ， 此 对 多 生 存 期 很 短 。 这 些 对 象 可 
能 是 普通 的 JavaBeans/POJO， 唯 一 特殊 的 是 他 们 正 与 (仅仅 一 个 ) Session + 

关联 。 一 旦 这 个 Session 被 关闭 ， 这 些 对 象 就 会 脱离 持久 化 状态 ， 这 样 就 可 被 应 
用 程序 的 任何 层 自 由 使 用 o (例如 ’ 用 作 跟 表示 层 打 交道 的 数据 传输 对 象 。 ) 


瞬 态 (transient) 和 脱 管 (detached) 的 对 象 及 其 集合 

那些 目前 没有 与 Session 关 联 的 持久 化 类 实例 。 他们 可 能 是 在 被 应 用 程序 实例 化 

后 ， 尚 未 进行 持久 化 的 对 象 。 也 可 能 是 因为 实例 化 他 们 的 Session 已 经 被 关闭 而 
脱离 持久 化 的 对 象 。 


事务 Transaction ( org.hibernate.Transaction ) 


(可 选 的 ) 应 用 程序 用 来 指定 原子 操作 单元 范围 的 对 象 ， 它 是 单线 程 的 ， 生 命 周期 
很 短 。 它 通过 抽象 将 应 用 从 底层 具体 的 JDBC、JTA 以 及 CORBA 事 务 隔离 开 。 某 
些 情况 下 ， 一 个 Session 之 内 可 能 包含 多 个 Transaction 对 象 。 尽管 是 否 使 用 
该 对 象 是 可 选 的 ， 但 无 论 是 使 用 底层 的 API 还 是 使 用 Transaction 对 象 ， 事 务 边 
界 的 开局 与 关闭 是 必 不 可 少 的 。 


ConnectionProvider ( org.hibernate.connection.ConnectionProvider ) 


(可 选 的 ) 生成 JDBC 连 接 的 工厂 (同时 也 起 到 连接 池 的 作用 ) 。 它 通过 抽象 将 应 
用 从 底层 的 Datasource 或 DriverManager 隔离 开 。 仅 供 开 发 者 扩展 /实现 用 ， 
并 不 暴露 给 应 用 程序 使 用 。 


TransactionFactory ( org.hibernate.TransactionFactory ) 


(可 选 的 ) 生成 Transaction 对 象 实例 的 工厂 。 仅 供 开发 者 扩展 /实现 用 ， 并 不 
暴露 给 应 用 程序 使 用 。 

扩展 接口 

Hibernate 提 供 了 很 多 可 选 的 扩展 接口 ， 你 可 以 通过 实现 它们 来 定制 你 的 持久 层 的 行 
为 。 具体 请 参考 API| 文 档 。 

在 特定 “轻型 "的 体系 结构 中 ， 应 用 程序 可 能 绕 过 

Transaction / TransactionFactory 以 及 ConnectionProvider 等 API 直 接 
跟 JTA 或 JDBC 打 交道 。 


2.2. 实例 状态 


一 个 持久 化 类 的 实例 可 能 处 于 三 种 不 同 状态 中 的 某 一 种 。 这 三 种 状态 的 定义 则 与 所 
谓 的 持久 化 上 下 文 (persistence context) A X ° Hibernate 的 Session 对 象 就 是 这 
个 所 谓 的 持久 化 上 下 文 : 

i A (transient) 

该 实例 从 未 与 任何 持久 化 上 下 文 关联 过 。 它 没有 持久 化 标识 (相当 于 主键 值 ) 。 
持久 化 (persistent) 


实例 目前 与 某 个 持久 化 上 下 文 有 关联 。 它 拥有 持久 化 标识 (相当 于 主键 值 ) ， 并 且 
可 能 在 数据 库 中 有 一 个 对 应 的 行 。 对 于 某 一 个 特定 的 持久 化 上 下 文 ，Hibernate 保 
证 持久 化 标识 与 Java 标 识 (其 值 代 表 对 象 在 内 存 中 的 位 置 ) 等 价 。 


脱 管 (detached) 


实例 曾经 与 某 个 持久 化 上 下 文 发 生 过 关联 ， 不 过 那个 上 下 文 被 关闭 了 ， 或 者 这 个 实 
例 是 被 序列 化 (serialize) 到 另外 的 进程 。 它 拥有 持久 化 标识 ， 并 且 在 数据 库 中 可 能 
存在 一 个 对 应 的 行 。 对 于 脱 管状 态 的 实例 ，Hibernate 不 保证 任何 持久 化 标识 和 
Java 标 识 的 关系 。 


2.3. IMX# S 


JMX 是 管理 Java 组 件 (Java components) 49 J2EE#% #2 ° Hibernate 可 以 通过 一 个 
JMX 标 准 服务 来 管理 。 在 这 个 发 行 版 本 中 ， 我 们 提供 了 一 个 MBean 接 口 的 实现 , 即 
org.hibernate.jmx.HibernateService ° 


WEA +o fy JBoss & Fl AR S 8 44% Hibernate= 部 署 为 一 个 JMX 服 务 的 例子 子 ， 您 可 以 


参考 JBoss 用 户 指 南 。 我 们 现在 说 一 下 在 Jboss 应 用 服务 器 上 ， 使 用 JMX 来 部 署 
Hibernate 的 好 处 : 


° o Hibernate 49 Session 对 象 的 生命 周期 可 以 自动 跟 一 个 JTA 事 
边界 绑 定 。 这 意味 着 你 无 需 手 工 开 关 Session 7, 这 项 工作 会 由 JBoss 
EJB 拦截 器 来 完成 。 你 再 也 不 用 担心 你 的 代码 中 的 事务 边界 了 (除非 你 想 利用 
Hibernate 提 供 可 选 的 Transaction APl 来 自己 写 一 个 便于 移植 的 的 持久 
层 )。 你 通过 调用 HibernateContext 来 访问 Session 。 


e。 HAR 部 署 : 通常 情况 下 ， 你 会 使 用 JBoss 的 服务 部 署 描述 符 (在 EAR 或 /和 SAR 
文件 中 ) 来 部 署 Hibernate JMX 服 务 。 这 种 部 署 方式 支持 所 有 常见 的 Hibernate 
SessionFactory 的 配置 选项 。 不 过 ， 你 仍 需 在 部 署 描述 符 中 ， 列 出 你 所 有 
的 映射 文件 的 名 字 。 如 果 你 使 用 HAR 部 署 方式 , JBoss 会 自动 探测 出 你 的 HAR 
文件 中 所 有 的 映射 文件 。 


这 些 选 项 更 多 的 描述 ， 请 参考 JBoss 应 用 程序 用 户 指 南 。 


将 Hibernate 以 部 着 为 JMX 服 务 的 另 一 个 好 处 > 是 可 以 查看 Hibernate 的 运行 时 统计 
信息 。 参 看 第 3.4.6 节 “ Hibernate 的 统计 (statistics) 机 制 ”. 


2.4. 对 JCA 的 支持 


Hibernate 也 可 以 被 配置 为 一 个 JCA 连 接 器 (JCA connector) 。 更 多 信息 请 参看 网 
站 。 请 注意 ，Hibernate 对 JCA 的 支持 ， 仍 处 于 实验 性 阶段 。 


2.5. 上 下 文 相 关 的 (Contextual) Session 


使 用 Hibernate 的 大 多 数 应 用 程序 需要 某 种 形式 的 “< 上下文 相 关 的 ”session > we 
session 在 整个 特定 的 上 下 文 范围 内 始终 有 效 。 然 而 ， 对 不 同类 型 的 应 用 程序 而 言 

要 为 什么 是 组 成 这 种 "上 下 文 "下 一 个 定义 通常 是 困难 的 ; 不 同 的 上 下 文 对 “当前 ”这 
概念 定义 了 不 同 的 范围 。 在 3.0 版 本 之 前 ， 使 用 Hibernate 的 程序 要 么 采用 自 a A 
的 基于 ThreadLocal 的 上 下 文 Session， 要 么 采用 Hibernateutil 这 样 的 辅助 
类 ， 要 么 采用 第 三 方 框架 (比如 Spring 或 Pico)， 它 们 提供 了 基于 代理 (proxy) 或 者 基 
于 拦截 器 (interception) 的 上 下 文 相 关 session 。 


从 3.0.1 版 本 开始 ，Hibernate 增 加 了 SessionFactory.getCurrentSession() 方 
法 。 一 开始 ， 它 假定 了 采用 JTA 事务 ， JTA 事务 定义 了 当前 session 的 范围 和 上 
下 文 (scope and context)。Hibernate 开 发 团队 坚信 ， 因 为 有 好 几 个 独立 

的 JTA TransactionManager 实现 稳定 可 用 ， 不 论 是 否 被 部 着 到 一 个 J2EE X 
中 ， 大 多 数 (假若 不 是 所 有 的 ) 应 用 程序 都 应 该 采用 JTA 事务 管理 。 基 于 这 一 点 
采用 ITA 的 上 下 文 相关 Session 可 以 满足 你 一 切 需 要 。 
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更 好 的 是 ， 从 3.1 开 始 ， ~SessionFactory.getCurrentSession() 的 后 台 实 现 是 
可 拔 插 的 。 因 此 ， 我 们 引入 了 新 的 扩展 接口 

( org.hibernate.context.CurrentSessionContext ) 和 新 的 配置 参数 

( hibernate.current_session_context_class )， 以 便 对 什么 是 “当前 
session” 的 范围 和 上 下 文 (scope and context) 的 定义 进行 拔 插 。 


请 参阅 org.hibernate.context.CurrentSessionContext 接口 的 Javadoc, 那 里 
有 关于 它 的 契约 的 详细 讨论 。 它 定义 了 单一 的 方法 ， currentSession() ， 特 定 
的 实现 用 它 来 负责 跟踪 当前 的 上 下 文 session。Hibernate 内 置 了 此 接口 的 三 种 实 

现 ,。 


e org.hibernate.context.JTASessionContext - 当前 session 根 据 JTA 来 
跟踪 和 界定 。 这 和 以 前 的 仅 支持 JTA 的 方法 是 完全 一 样 的 。 详 情 请 参阅 
Javadoc ° 


e org.hibernate.context.ThreadLocalSessionContext - 当前 session 通 
过 当前 执行 的 线程 来 跟踪 和 界定 。 详 情 也 请 参阅 Javadoc。 


e org.hibernate.context.ManagedSessionContext - 当前 session 通过 当前 
执行 的 线程 来 跟踪 和 界定 。 但 是 ， 你 需要 负责 使 用 这 个 类 的 静态 方法 
将 Session 实例 绑 定 、 或 者 取消 绑 定 ， 它 并 不 会 打开 (open)、flush 或 者 关闭 
(close) 任 何 Session 。 


前 两 种 实现 都 提供 了 “每 数据 库 事务 对 应 一 个 sessiom" 的 编程 模型 ， nae 求 
一 个 session。Hibernate session 的 起 始 和 终结 由 数据 库 事务 的 生存 来 控制 。 假 若 你 
在 纯粹 的 Java SE 之 上 采用 自行 编写 代码 来 管理 事务 ,而 不 使 用 JTA ， see 
Hibernate Transaction API 来 把 底层 事务 实现 从 你 的 代码 中 隐藏 看 。 如 果 你 使 
用 JTA， 请 使 用 STA ti 口 来 管理 Transaction。 如 果 你 在 支持 CMT 的 EJB 容 器 中 执行 
代码 ， 事 务 边界 是 声明 式 定 义 的 ， 你 不 需要 在 代码 中 进行 任何 事务 或 session 管 理 操 
作 。 请 参阅 第 11 章 事务 和 并 发 一 节 来 阅读 更 多 的 内 容 和 示例 代码 。 


hibernate.current_session_context_class 配置 参数 定义 了 应 该 采用 哪 

个 org.hibernate.context.CurrentSessionContext 实现 。 注 意 ， 为 了 向 下 兼 
容 ， 如 果 未 配置 此 参数 ， 但 是 存 
在 org.hibernate.transaction.TransactionManagerLookup 的 配置 ， 
Hibernate 会 采用 org.hibernate.context.JTASessionContext 。 一 般 而 言 ， 此 
参数 的 值 指 明了 要 使 用 的 实现 类 的 全 名 ， 但 那 三 种 内 置 的 实现 可 以 使 用 简写 ， 

即 "jta"、"thread" 和 "managed"。 


3.1. 可 编程 的 配置 方式 
3.2. 获得 SessionFactory 
3.3. JDBC 连 接 
3.4. 可 选 的 配置 属性 

o 3.4.1. SQL 方言 
3.4.2. 外 连接 抓 取 (Outer Join Fetching) 
3.4.3. 二 进 制 流 (Binary Streams) 
3.4.4. 二 级 缓存 与 查询 缓存 
3.4.5. 查询 语言 中 的 替换 

o 3.4.6. Hibernate 的 统计 (statistics) 机 制 
3.5. 日 志 
3.6. 实现 NamingStrategy 
3.7. XML 配置 文件 
3.8. J2EE 应 用 程序 服务 器 的 集成 

o 3.8.1. 事务 策略 配置 

o 3.8.2. JNDI 绑 定 的 SessionFactory 

o 3.8.3. 在 JTA 环 境 下 使 用 Current Session context (当前 session 上 下 文 ) 管 

理 
o 3.8.4. JMX 部 署 


由 于 Hibernate 是 为 了 能 在 各 种 不 同 环境 下 工作 而 设计 的 , 因此 存在 着 大 量 的 配置 参 
数 . 幸运 的 是 多 数 配置 参数 都 有 比较 直观 的 默认 值 , 并 有 随 Hibernate 一 同 分 发 的 配 
置 样 例 hibernate.properties (位 于 etc/ ) 来 展示 各 种 配置 选项 . 所 需 做 的 仅 

仅 是 将 这 个 样 例文 件 复制 到 类 路 径 (classpath) 下 并 做 一 些 自 定义 的 修改 . 


3.1. 可 编程 的 配置 方式 


一 个 org.hibernate.cfg.Configuration 实例 代表 了 一 个 应 用 程序 中 Java 类 型 
到 SQL 数据 库 映射 的 完整 集合 Configuration 被 用 来 构建 一 个 (不 可 变 的 
(immutable)) SessionFactory . 映射 定义 则 由 不 同 的 XML 映射 定义 文件 编译 而 来 . 


你 可 以 直接 实例 化 Configuration 来 获取 一 个 实例 ， 并 为 它 指 定 XML 了 映射 定义 X 
件 . 如 果 映 射 定 义 文件 在 类 路 径 (classpath) 中 , 请 使 用 addResource() : 


Configuration cfg = new Configuration() 
.addResource("Item.hbm.xm1") 
.addResource("Bid.hbm. xml"); 


一 个 替代 方法 (有 时 是 更 好 的 选择 ) 是 ， 指 定 被 映射 的 类 ， 让 Hibernate 帮 你 寻找 映 
射 定义 文件 : 


Configuration cfg = new Configuration() 
.addClass(org.hibernate.auction.Item.class) 
.addClass(org.hibernate.auction.Bid.class); 
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/org/hibernate/auction/Item.hbm.xml 和 
/org/hibernate/auction/Bid.hbm.xml 映射 定义 文件 . 这 种 方式 消除 了 任何 对 

文件 名 的 硬 编码 (hardcoded). 


Configuration 也 允许 你 指定 配置 属性 : 


Configuration cfg = new Configuration() 
.addClass(org.hibernate.auction.Item.class) 
.addClass(org.hibernate.auction.Bid.class) 
.setProperty("hibernate.dialect", "org.hibernate.dialect.MyS 

QLInnoDBDialect") 

.setProperty("hibernate.connection.datasource", "java:comp/e 
nv/jdbc/test") 
.setProperty("hibernate.order_updates", "true"); 


当然 这 不 是 唯一 的 传递 Hibernate 配 置 属性 的 方式 , 其 他 可 选 方式 还 包括 : 


1. 传 一 个 java.util.Properties 实例 给 
Configuration.setProperties() . 


2. 将 hibernate.properties 放置 在 类 路 径 (classpath) 的 根 目 录 下 (root 
directory). 


3. 通过 java -Dproperty=value 来 设置 系统 ( System At. 
4. 在 hibernate.cfg.xml 中 加 入 元 素 &lt;property&gt; (Mit). 
如 果 想 尽快 体验 Hibernate，hibernate.properties 是 最 简单 的 方式 . 


Configuration 实例 被 设计 成 启动 期 间 (startup-time) 对 象 ,一 
E SessionFactory 创建 完成 它 就 被 丢弃 了 . 


3.2. 获得 SessionFactory 


当 所 有 映射 定义 被 Configuration 解析 后 , 应 用 程序 必须 获得 一 个 用 于 构 
造 Session 实例 的 工厂 . 这 个 工厂 将 被 应 用 程序 的 所 有 线程 共享 : 


SessionFactory sessions = cfg.buildSessionFactory(); 


Hibernate 允 许 你 的 应 用 程序 创建 多 个 SessionFactory 实例 . 这 对 使 用 多 个 数据 
库 的 应 用 来 说 很 有 用 . 


3.3. JDBC 连 接 


通常 你 希望 SessionFactory 来 为 你 创建 和 缓存 (pool)JDBC 连 接 . 如 果 你 采用 这 种 
方式 , 只 需要 如 下 例 所 示 那 样 ， 打 开 一 个 Session : 


Session session = sessions.openSession(); // open a new Session 


一 旦 你 需要 进行 数据 访问 时 , 就 会 从 连接 池 (connection pool) 获 得 一 个 JDBC 连 接 . 


为 了 使 这 种 方式 工作 起 来 , 我 们 需要 向 Hibernate 传 递 一 些 JDBC 连 接 的 属性 . 所 有 
Hibernate 属 性 的 名 字 和 语义 都 在 org.hibernate.cfg.Environment 中 定义 .我 
们 现在 将 描述 JDBC 连 接 配置 中 最 重要 的 设置 . 


如 果 你 设置 如 下 属性 ，Hibernate 将 使 用 java.sql.DriverManager 来 获得 (和 缓 
存 )JDBC 连 接 : 


表 3.1. Hibernate JDBC 属 性 


属性 名 用 途 
hibernate.connection.driver_class jdbc 驱 动 类 
hibernate.connection.url jdbc URL 
hibernate.connection.username 数据 库 用 户 
hibernate.connection.password 数据 库 用 户 密 码 
hibernate.connection.pool_size 连接 池 容 量 上 限 数目 


但 Hibernate 自 带 的 连接 池 算 法 相当 不 成 熟 . 它 只 是 为 了 让 你 快 些 上 手 ， 并 不 适合 用 
于 产品 系统 或 性 能 测试 中 。 出 于 最 佳 性 能 和 稳定 性 考虑 你 应 该 使 用 第 三 方 的 连接 
池 。 只 需要 用 特定 连接 池 的 设置 替换 hibernate.connection.pool_size 即 可 。 
这 将 关闭 Hibernate 自 带 的 连接 池 . 例如 , 你 可 能 会 想 用 C3P0. 


C3P0 是 一 个 随 Hibernate 一 同 分 发 的 开源 的 JDBC 和 连接 池 , 它 位 于 lib 目录 下 。 如 
果 你 设置 了 hibernate.c3p0.* 相关 的 属性 , Hibernate 将 使 用 

C3POConnectionProvider 来 缓存 JDBC 连 接 . 如 果 你 更 原意 使 用 Proxool, 请 参考 
发 行 包 中 的 hibernate.properties 并 到 Hibernate 网 站 获取 更 多 的 信息 . 


这 是 一 个 使 用 C3P0 的 hibernate.properties 样 例 文件 : 


hibernate.connection.driver_class = org.postgresql.Driver 
hibernate.connection.url = jdbc:postgresql://localhost/mydatabas 
e 
hibernate.connection.username 
hibernate.connection.password 
hibernate.c3p0.min_size=5 
hibernate.c3p0.max_size=20 
hibernate.c3p0.timeout=1800 
hibernate.c3p0.max_statements=50 

hibernate.dialect = org.hibernate.dialect .PostgreSQLDialect 


myuser 
secret 


为 了 能 在 应 用 程序 服务 器 (application server) Y 4] Hibernate, 应 当 总 是 将 
Hibernate 配置 成 从 注册 在 JNDI 中 的 Datasource 处 获得 连接 ， 你 至 少 需要 设置 下 
列 属性 中 的 一 个 : 


表 3.2. Hibernate 数 据 源 属性 


属性 名 用 途 
hibernate.connection.datasource 数据 源 JNDI/ 名 字 
hibernate. jndi.url JNDI 提 供 者 的 URL (可 选 ) 
JNDI 
hibernate.jndi.class InitialContextFactory 类 (可 
选 ) 
hibernate.connection.username 数据 库 用 户 (可 选 ) 
hibernate.connection.password 数据 库 用 户 密码 (可 选 ) 


这 是 一 个 使 用 应 用 程序 服务 器 提供 的 JNDI 数 据 源 的 hibernate.properties 样 例 
文件 : 


hibernate.connection.datasource = java:/comp/env/jdbc/test 
hibernate.transaction.factory_class = \ 

org.hibernate. transaction. JTATransactionFactory 
hibernate.transaction.manager_lookup_class = \ 

org. hibernate. transaction. JBossTransactionManagerLookup 
hibernate.dialect = org.hibernate.dialect .PostgreSQLDialect 


从 JNDI 数 据 源 获得 的 JDBC 连 接 将 自动 参与 到 应 用 程序 服务 器 中 容器 管理 的 事务 
(container-managed transactions) 中 去 . 


任何 连接 (connection) 属 性 的 属性 名 都 要 以 "hibernate.connnection "开头 . 例如 ， 
你 可 能 会 使 用 hibernate.connection.charSet 来 指定 字符 集 charset. 


通过 实现 org. hibernate.connection.ConnectionProvider 接口 ， 你 可 以 定义 
属于 你 自己 的 获得 JDBC 连 接 的 插件 策略 。 通 过 设 
置 hibernate.connection.provider_class ， 你 可 以 选择 一 个 自 定 义 的 实现 . 


3.4. 可 选 的 配置 属性 


有 大 量 属性 能 用 来 控制 Hibernate 在 运行 期 的 行为 . 它们 都 是 可 选 的 , 并 拥有 适当 的 
默认 值 . 


警告 : 其 中 一 些 属性 是 "系统 级 (system-level) 的 ". 系统 级 属性 只 能 通 
过 java -Dproperty=value 或 hibernate.properties 来 设置 , 而 不 能 用 上 面 
描述 的 其 他 方法 来 设置 . 


表 3.3. Hibernate 配 置 属性 


属性 名 用 途 


一 个 Hibernate Dialect 类 名 允 
许 Hibernate 针 对 特定 的 关系 数据 
库 生 成 优化 的 SQL. 取 值 


full.classname.of.Dialect 


输出 所 有 SQL 语 名 到 控制 台 . 有 
一 个 另外 的 选择 是 

hibernate. show_ sql 把 org.hibernate.SQL 这 个 
log category 设 为 debug ° eg. 
true | false 


hibernate.dialect 


在 log 和 console 中 打印 出 更 漂亮 
的 SQL。 取 值 true | false 


在 生成 的 SQL 中 , 将 给 定 的 

schema/tablespace 附 加 于 非 全 

限定 名 的 表 名 上 . 取 值 
SCHEMA_NAME 


在 生成 的 SQL 中 , 将 给 定 的 
hibernate.default_catalog catalog 附 加 于 非 全 限定 名 的 表 名 
上 . 取 值 CATALOG_NAME 


hibernate. format_sql 


hibernate.default_schema 


SessionFactory 创建 后 ， 将 
自动 使 用 这 个 名 字 绑 定 到 JNDI 
中 . 取 值 


jndi/composite/name 


为 单 向 关联 (一 对 一 , 多 对 一 ) 的 外 
连接 抓 取 (outer join fetch) 树 

hibernate.max_fetch_depth 设置 最 大 深度 . MA 9 意味 着 将 
关闭 默认 的 外 连接 抓 取 . 取 值 建 
议 在 0 到 3 之 间 取 值 


为 Hibernate 关 联 的 批量 抓 取 设 置 
hibernate.default_batch_fetch_size 默认 数量 , 取 值 建议 的 取 值 


hibernate.session_factory_name 


hibernate.default_entity_mode 


hibernate.order_updates 


hibernate.generate_statistics 


hibernate.use_identifer_rollback 


hibernate.use_sql_ comments 
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为 由 这 个 SessionFactory 4T 
开 的 所 有 Session 指 定 上 默认 的 实 
体 表现 模式 . 取 值 

dynamic-map , dom4j 

pojo 

强制 Hibernate 按 照 被 更 新 数据 的 
主键 ， 为 SQL 更 新 排序 。 这 么 做 
将 减少 在 高 并 发 系统 中 事务 的 死 
锁 。 取 值 true | false 


4o RFE B , Hibernate 将 收集 有 助 
于 性 能 调节 的 统计 数据 . 取 值 
true | false 


如 果 开 启 , 在 对 象 被 删除 时 生成 
的 标识 属性 将 被 重 设 为 默认 值 . 
取 值 true | false 


如 果 开 启 , Hibernate 将 在 SQL 中 

生成 有 助 于 调试 的 注释 信息 , R 

认 值 为 false . 取 值 true | 
false 


表 3.4. Hibernate JDBC 和 连接 (connection) 属 性 


属性 名 


hibernate. jdbc.fetch_size 


hibernate. jdbc.batch_size 


hibernate. jdbc.batch_versioned_data 


hibernate. jdbc.factory_class 


hibernate. jdbc.use_scrollable_resultset 


Fil a 


非 零 值 ， 指 定 JDBC 抓 取 数 量 
用 Statement.setFetchSi 


非 零 值 ， 允许 Hibernate 使 用 
建议 取 5 到 30 之 问 的 值 


如 果 你 想 让 你 的 JDBC 驱 动力 
正确 的 行 计 数 ,那么 将 此 属 + 
选项 通常 是 安全 的 ). 同时 ， 上 
化 的 数据 使 用 批量 DML. RE 
true | false 
选择 一 个 自 定义 的 Batcher 
这 个 配置 属性 . eg. classné 
#17 Hibernatet# F JDBC2 4 
用 用 户 提供 的 JDBC 连 接 时 ， 
则 Hibernate 会 使 用 连接 的 元 
false 


在 JDBC 读 


hibernate.jdbc.use_streams_for_binary 


hibernate.jdbc.use_get_generated_keys 


hibernate.connection. 


hibernate.connection. 


hibernate.connection. 


hibernate.connection. 


provider_class 


isolation 


autocommit 


release_mode 


写 binary (二 进 制 ) 或 se 
的 类 型 时 使 用 流 (stream)( 系 : 


false 


在 数据 插入 数据 库 之 后 ， 允 - 

PreparedStatement .getG 
取 数 据 库 生成 的 key( 键 )。 需 
JRE1.4+, 如 果 你 的 数据 库 驱 
识 生 成 器 时 遇 到 问题 ， 请 将 ， 
下 将 使 用 连接 的 元 数据 来 判 ， 
true&#124; false 


自 定义 ConnectionProvide 


Hibernate 提 供 JDBC 连 接 . 到 
classname.of.Connectio 


设置 JDBC 事 务 隔离 级 别 . & 
看 java.sql.Connection 
SL, 但 请 注意 多 数 数据 库 都 了 
值 EESE 


pepe ee aed 
(不 建议 ). 取 值 true | fa 


指定 Hibernate 在 何 时 释放 J[ 
| Session #& E A, K H RAK 
JDBC# 4. 对 于 应 用 程序 服 
当 使 用 after_statement 

后 ， 都 会 主动 的 释放 连接 .天 
用 after_transaction 在 
是 合理 的 ，auto 44A JTAF 
择 after_statement ,为 J 
择 after_transaction . 


取 值 auto (默认 )| on_close | after_transaction | after_statement 


ee SessionFactory.openSession 得 到 的 Session 起 作 
用 。 对 于 通过 SessionFactory. getCurrentSession 得 到 的 Session ， 所 配置 


的 CurrentSessionContext 实现 控制 这 


2.5 节 “ 上 下 文 相 关 的 〈Contextual) Session” ° 


|| hibernate.connection. 


& 3.5. Hibernate 4 2 tt 


文 些 Session 的 连接 释放 模式 。 请 参阅 第 


_&lt;propertyName&gt;_ | 将 JDBC 属 

性 propertyName 传递 到 DriverManager.getConnection() 中 去 .|| 
hibernate. jndi._&lt;propertyName&gt;_ | 将 属性 propertyName 传递 到 
JNDI InitialcontextFactory 中 去 .| 


hibernate.cache. 


hibernate.cache. 


hibernate.cache. 


hibernate.cache 


hibernate.cache. 


hibernate.cache. 


hibernate.cache. 


属性 名 


provider_class 


use_minimal_puts 


use_query_cache 


.use_second_level_cache 


query_cache_factory 


region_prefix 


use_structured_entries 


& 3.6. Hibernate = 4 %14 


自 定 义 的 CacheProvider 的 
名 . 取 值 


classname.of.CacheProvi 


以 频繁 的 读 操 作为 代价 , 优化 - 
绥 存 来 最 小 化 写 操作 . 在 
Hibernate3 中 ， 这 个 设置 对 的 
缓存 非常 有 用 , 对 集群 缓存 的 ! 
me? Kiet eo. PAE 
true&#124; false 


允许 查询 绥 存 , 个 别 查询 仍然 : 
被 设置 为 可 缓存 的 . 取 值 


true&#124; false 
能 用 来 完全 禁止 使 用 二 级 缓存 
那些 在 类 的 映射 定义 中 指 


Z &lt;cache&gt; 的 类 ， 会 
认 开 局 二 级 缓存 . 取 值 
true&#124; false 


自 定义 实现 QueryCache 7#' 
类 名 , 默认 为 内 建 

的 StandardQueryCache . ¥ 
classname.of.QueryCache 


=H EH RIBS ITA. 取 值 
prefix 


强制 Hibernate 以 更 人 性 化 的 不 
将 数据 存 入 二 级 缓存 . 取 值 
true&#124; false 


属性 名 


hibernate.transaction.factory_class 


jta.UserTransaction 


hibernate. transaction.manager_lookup_class 


hibernate.transaction.flush_before_completion 


hibernate.transaction.auto_ close session 


表 3.7. 其 他 属性 


一 个 TransactionFi 
Hibernate Transact 


为 JIDBCTransactio 
classname.of.Tra 


一 个 JNDI 名 字 ， 

被 JTATransaction 

器 获取 JTA Usertra 
jndi/composite/n 


一 个 TransactionM 
使 用 JVM 级 缓存 ， 或 
器 的 时 候 需要 该 类 . | 
classname.of.Tra 


如 果 开 启 , session 在 

(flush) 。 现 在 更 好 的 

下 文 管理 。 请 参见 第 
(Contextual) Sess 
false 


如 果 开 启 , session 在 
闭 。 现 在 更 好 的 方法 
管理 。 请 参见 第 2.5 
(Contextual) Sess 
false 


属性 名 


hibernate.current_session_context_class 


hibernate.query.factory_class 


hibernate. query.substitutions 


hibernate.hbm2dd1.auto 


hibernate.cglib.use_reflection_optimizer 


为 "当前 " Session HE <— 
情 ， 请 参见 第 2.5 节 “ 上 下 . 
jta | thread | manag 


选择 HQL 解 析 器 的 实现 . 取 
org.hibernate.hql.ast 
org.hibernate.hql.cla 


将 Hibernate 查 询 中 的 符号 
名 或 常量 名 字 ). PAE 
hqlLiteral=SQL_LITERA 


在 SessionFactory 创建 ! 
schema 的 DDL 寻 出 到 数据 ， 
闭 SessionFactory 时 ，: 
| update | create | c 
开 忆 CGLIB 来 替代 运行 时 反 
时 比较 有 用 . 注意 即使 关闭 : 
能 在 hibernate.cfg.xml 


3.4.1. SQL7 È 


你 应 当 总 是 为 你 的 数据 库 将 hibernate.dialect 属性 设置 成 正确 的 
org.hibernate.dialect.Dialect FR. 如 果 你 指定 一 种 方言 , Hibernate 将 为 上 
面 列 出 的 一 些 属性 使 用 合理 的 默认 值 , 为 你 省 去 了 手工 指定 它们 的 功夫 . 


表 3.8. Hibernate SQL 方言 ( hibernate.dialect ) 


RDBMS 
DB2 
DB2 AS/400 
DB2 OS390 
PostgreSQL 
MySQL 
MySQL with InnoDB 


MySQL with 
MyISAM 


Oracle (any version) 
Oracle 9i/10g 
Sybase 

Sybase Anywhere 


Microsoft SQL 
Server 


SAP DB 
Informix 
HypersonicSQL 
Ingres 

Progress 

Mckoi SQL 
Interbase 
Pointbase 
FrontBase 


Firebird 


org. 


org 


org. 


org. 


org 


org. 


org. 


org. 


org. 


org 


org. 


org. 


org. 


org. 


org 


org. 


org. 


org 


org. 
org. 
org. 


org. 


hibernate. 
‘hibernate. 
hibernate. 
hibernate. 
.hibernate. 


hibernate. 


hibernate. 


hibernate. 
hibernate. 
.hibernate. 


hibernate. 


hibernate. 


hibernate. 
hibernate. 
‘hibernate. 
hibernate. 
hibernate. 
‘hibernate. 
hibernate. 
hibernate. 
hibernate. 


hibernate. 


a 
万 号 


dialect. 
dialect. 
dialect. 
dialect: 
dialect. 


dialect. 


dialect. 


dialect. 
dialect. 
dialect. 


dialect. 


dialect. 


dialect. 
dialect. 
dialect. 
dialect. 
dialect. 
dialect: 
dialect. 
dialect. 
dialect. 


dialect. 


DB2Dialect 
DB2400Dialect 
DB2390Dialect 
PostgreSQLDialect 
MySQLDialect 


MySQLInnoDBDialect 
MySQLMyISAMDialect 


OracleDialect 
Oracle9Dialect 
SybaseDialect 


SybaseAnywhereDialect 
SQLServerDialect 


SAPDBDialect 
InformixDialect 
HSQLDialect 
IngresDialect 
ProgressDialect 
MckoiDialect 
InterbaseDialect 
PointbaseDialect 
FrontbaseDialect 


FirebirdDialect 


3.4.2. 外 连接 抓 取 (Outer Join Fetching) 


如 果 你 的 数据 库 支持 ANSI, Oracle 或 Sybase 风格 的 外 连接 ， 外 连接 抓 取 通常 能 通过 
限制 往返 数据 库 次 数 (更 多 的 工作 交 由 数据 库 自 己 来 完成 ) 来 提高 效率 . 外 连接 抓 取 
允许 在 单个 SELECT SQL 语句 中 ， 通 过 many-to-one, one-to-many, many-to-many 
和 one-to-one 关 联 获 取 连 接 对 象 的 整个 对 象 图 . 

将 hibernate.max_fetch_depth 设 为 0 能 在 全 局 范围 内 禁止 外 连接 抓 取 . 设 
为 1 或 更 高 值 能 启用 one-to-one 和 many-to-oneouter 关 联 的 外 连接 抓 取 , 它们 通过 
fetch="join" 来 映射 . 


参见 第 19.1 节 “ 抓 取 策略 (Fetching strategies) "获得 更 多 信息 . 


3.4.3. 二 进 制 流 (Binary Streams) 


Oracle 限 制 那些 通过 JDBC 了 驱动 传输 的 字 节 数组 的 数目 . 如 果 你 希望 使 
用 二 进 值 (binary) 或 可 序列 化 的 (serializable) 类 型 的 大 对 象 , 你 应 该 开启 
hibernate.jdbc.use_streams_for_binary 属性 . 这 是 系统 级 属性 . 


3.4.4. 二 级 缓存 与 查询 缓存 


以 hibernate.cache 为 前 组 的 属性 允许 你 在 Hibernate 中 ， 使 用 进程 或 群集 范围 
内 的 二 级 缓存 系统 . 参见 第 19.2 节 “ 二 级 缓存 (The Second Level Cache) "获取 
更 多 的 详情 . 


3.4.5. 查询 语言 中 的 替换 


你 可 以 使 用 hibernate.query.substitutions 在 Hibernate 中 定义 新 的 查询 符号 . 
例如 : 


hibernate.query.substitutions true=1, false=0 
将 导致 符号 true 和 false 在 生成 的 SQL 中 被 翻译 成 整数 常量 . 


hibernate.query.substitutions toLowercase=LOWER 


将 允许 你 重 命名 SQL 中 的 LOWER 函数 . 


3.4.6. Hibernate 的 统计 (statistics) 机 制 


如 果 你 开启 hibernate.generate statistics , 那么 当 你 通过 
SessionFactory.getStatistics() 调整 正在 运行 的 系统 时 ，Hibernate 将 导出 大 

量 有 用 的 数据 . Hibernate 其 至 能 被 配置 成 通过 JMX 导 出 这 些 统计 信息 . 参 

考 org.hibernate.stats 中 接口 的 Javadoc， 以 获得 更 多 信息 . 


3.5. 日 志 


Hibernate 使 用 Apache commons-logging 来 为 各 种 事件 记录 日 志 . 


commons-logging 将 直接 输出 到 Apache Log4j( 如 果 在 类 路 径 中 包括 log4j.jar ) 
或 JDK1.4 logging (如 果 运 行 在 JDK1.4 或 以 上 的 环境 下 ). 你 可 以 

从 http://jakarta.apache.org 下 载 Log4j. 要 使 用 Log4j， 你 需要 

将 log4j.properties 文件 放置 在 类 路 径 下 , 随 Hibernate 一 同 分 发 的 样 例 属性 文 
件 在 src/ 目录 下 . 


我 们 强烈 建议 你 熟 sae a alle 日 志 ERA TE EA a ， 我 们 做 了 
工作 ， 使 Hibernate 的 日 志 可 能 地 详细 . 这 是 必要 的 查 错 利器 . 最 感 兴趣 的 
志 分 类 有 如 下 这 些 : 


表 3.9. Hibernate 日 志 类 别 


ae 功能 
org.hibernate. SQL aa DML 语 句 被 执行 时 为 它们 记录 
Co lS 为 所 有 JDBC 参 数 记 录 日 志 


在 所 有 SQL DDL 语 名 执行 时 为 它们 记录 日 


在 session 清 洗 (flush) 时 ， 为 所 有 与 其 关联 
的 实体 (最 多 20 个 ) 的 状态 记录 日 志 


org.hibernate.tool.hbm2dd1 


org. hibernate.pretty 


org.hibernate.cache 为 所 有 二 级 缓存 的 活动 记录 日 志 
org.hibernate.transaction 为 事务 相关 的 活动 记录 日 志 
org.hibernate. jdbc 为 所 有 JDBC 资 源 的 获取 记录 日 志 
a E ee 的 时 候 , 记 录 HQL 和 SQL 的 AST 
org.hibernate.secure 为 JAAS 认 证 请 求 做 日 志 


为 任何 Hibernate 相 关 信 息 做 日 志 (信息 量 
esa 较 大 , 但 对 查 错 非常 有 帮助 ) 
在 使 用 Hibernate 开 发 应 用 程序 时 , 你 应 当 总 是 为 org.hibernate.SQL 开 
È debug 级 别 的 日 志 记 录 , 或 者 开启 hibernate.show_sql 属性 。 


3.6. 实现 NamingStrategy 


org.hibernate.cfg.NamingStrategy 接口 允许 你 为 数据 库 中 的 对 象 和 schema 
元 素 指 定 一 个 “命名 标准 ”. 


可 能 会 提供 一 些 通 过 Java 标 识 生成 数据 库 标 识 或 将 映射 定义 文件 中 "逻辑 " 表 / 列 名 
peor ea 的 规则 . 这 个 特性 有 助 于 减少 元 长 的 映射 定义 文件 . 


在 加 入 映射 定义 前 ， 你 可 以 调用 Configuration.setNamingStrategy() 指定 一 
个 不 同 的 命名 策略 : 


SessionFactory sf = new Configuration() 
.setNamingStrategy(ImprovedNamingStrategy. INSTANCE ) 
.addFile("Item.hbm.xm1") 

.addFile("Bid.hbm.xm1" ) 
.buildSessionFactory(); 


org.hibernate.cfg.ImprovedNamingStrategy 是 一 个 内 建 的 命名 策略 , 对 一 些 
应 用 程序 而 言 ， 可 能 是 非常 有 用 的 起 点 . 


3.7. XML 配置 文件 


另 一 个 配置 方法 是 在 hibernate.cfg.xml 文件 中 指定 一 套 完 整 的 配置 . 这 个 文件 
可 以 当成 hibernate.properties 的 替代 。 若 两 个 文件 同时 存在 ， 它 将 履 盖 前 者 
的 属性 . 


XML 配置 文件 被 默认 是 放 在 CLASSPATH 的 根 目录 下 . 这 是 一 个 例子 : 


<?xml version='1.0' encoding='utf-8'?> 

<!DOCTYPE hibernate-configuration PUBLIC 
"-//Hibernate/Hibernate Configuration DTD//EN" 
"http://hibernate.sourceforge.net/hibernate-configuration-3. 

0.dtd"> 


<hibernate-configuration> 


<!-- YA/jndi/name# < 2] INDI47SessionFactory*] --> 
<session-factory 
name="jJava:hibernate/SessionFactory"> 


<!-- 属性 --> 

<property name="connection.datasource">java:/comp/env/jd 
bc/MyDB</property> 

<property name="dialect">org.hibernate.dialect .MySQLDial 
ect</property> 

<property name="Show_sql">false</property> 

<property name="transaction. factory _class"> 

org.hibernate. transaction. JTATransactionFactory 

</property> 

<property name="jta.UserTransaction">java:comp/UserTrans 
action</property> 


<!-- 映射 定义 文件 --> 
<mapping resource="org/hibernate/auction/Item.hbm.xml"/> 
<mapping resource="org/hibernate/auction/Bid.hbm. xm1"/> 


<!-- 缓存 设置 --> 

<class-cache class="org.hibernate.auction.Item" usage="r 
ead-write"/> 

<class-cache class="org.hibernate.auction.Bid" usage="re 
ad-only"/> 

<collection-cache collection="org.hibernate.auction.Item 
.bids" usage="read-write"/> 


</session-factory> 


</hibernate-configuration> 


如 你 所 见 , 这 个 方法 优势 在 于 ， 在 配置 文件 中 指出 了 映射 定义 文件 的 名 字 . 一 旦 你 需 
要 调整 Hibernate 的 缓存 ， hibernate.cfg.xml 也 是 更 方便 . 注意 ， 使 

用 hibernate.properties 还 是 hibernate.cfg.xml 完全 是 由 你 来 决定 , 除了 
上 面 提 到 的 XML 语 法 的 优势 之 外 , 两 者 是 等 价 的 . 


使 用 XML 配置 ， 使 得 启动 Hibernate 变 的 异常 简单 , 如 下 所 示 ， 一 行 代码 就 可 以 摘 


FE: 


SessionFactory sf = new Configuration().configure().buildSession 
Factory(); 


你 可 以 使 用 如 下 代码 来 添加 一 个 不 同 的 XML 配置 文件 


SessionFactory sf = new Configuration() 
.configure("catdb.cfg. xml") 
.buildSessionFactory(); 


3.8. J2EE 应 用 程序 服务 器 的 集成 


针对 J2EE 体 系 ,Hibernate 有 如 下 几 个 集成 的 方面 : 


A= 


S 


容器 管理 的 数据 源 (Container-managed datasources): Hibernate 能 使 用 通过 容 
器 管理 ， 并 由 JNDI 提 供 的 JDBC 连 接 . 通常 , 特别 是 当 处 理 多 个 数据 源 的 分 布 式 


事务 的 时 候 , 由 一 个 JTA 兼 容 的 TransactionManager 和 一 个 
ResourceManager 来 处 理事 务 管 理 (CMT, 容器 管理 的 事务 ). 当然 你 可 以 通过 
编程 方式 来 划分 事务 边界 (BMT, Bean 管 理 的 事务 ). 或 者 为 了 代码 的 可 移植 性 ， 
你 也 也 许 会 想 使 用 可 选 的 Hibernate Transaction API. 


自动 JND/ 绑 是: Hibernate 可 以 在 局 动 后 将 SessionFactory A% Æ 2] JNDI. 


JTA Session% Z: Hibernate Session 可 以 自动 绑 定 到 JTA 事 务 作 用 的 范围 . 
R T 需 简 单 地 从 JNDI 查 找 SessionFactory 并 获得 当前 的 Session . 当 JTA 事 

完成 时 , 让 Hibernate 来 处 理 Session 的 清洗 (flush) 与 关闭 . 事务 的 划分 可 以 
ap 明 式 的 (CMT), 也 可 以 是 编程 式 的 (BMT/UserTransaction). 


JMX 部 署 : 如 果 你 使 用 支持 JMX 应 用 程序 服务 器 (如 , JBoss AS), 那么 你 可 以 选 
择 将 Hibernate 部 署 成 托管 MBean. 这 将 为 你 省 去 一 行 从 Configuration 构 
建 SessionFactory 的 启动 代码 . 容器 将 启动 你 的 HibernateService , #% 
美 地 处 理 好 服务 问 的 依赖 关系 bende 动 前 ， 数 据 源 必须 是 可 用 的 ， 等 
F). 


如 果 应 用 程序 服务 器 抛 出 "connection containment" 异 常 , 根据 你 的 环境 ， 也 许 该 将 
配置 属性 hibernate.connection.release_mode 设 为 after_statement . 


3.8.1. 事务 梨 略 配置 


在 你 的 架构 中 ，Hibernate 的 Session API 是 独立 于 任何 事务 分 界 系统 的 . 如 果 你 
让 Hibernate 通 过 连接 池 直 接 使 用 JDBC, 你 需要 调用 JDBC API 来 打开 和 关闭 你 的 事 
务 . 如 果 你 运行 在 J2EE 应 用 程序 服务 器 中 , 你 也 许 想 用 Bean 管 理 的 事务 并 在 需要 的 
时 候 调 用 JTA API 和 UserTransaction . 


为 了 让 你 的 代码 在 两 种 (或 其 他 ) 环 境 中 可 以 移植 ， 我 们 建议 使 用 可 选 的 Hibernate 
Transaction API, 它 包 装 并 隐藏 了 底层 系统 . 你 必须 通过 设置 Hibernate 配 置 属 
性 hibernate.transaction.factory_class 来 指定 一 个 Transaction 实例 的 


工厂 类 . 

有 三 个 标准 (内 建 ) 的 选择 : 
org.hibernate.transaction.JDBCTransactionFactory 

委托 给 数据 库 (JDBC) 事 务 (RU) 
org.hibernate.transaction.JTATransactionFactory 


如 果 在 上 下 文 环境 中 存在 运行 着 的 事务 (如 ,EJB 会话 Bean 的 方法 ), 则 委托 给 容 
理 的 事务 , 否则 ， 将 启动 一 个 新 的 事务 ， 并 使 用 Bean 管 理 的 事务 . 


org.hibernate.transaction.CMTTransactionFactory 


2, 


7 


ays 
wit 


委托 给 容器 管理 的 JTA 事 务 
你 也 可 以 定义 属于 你 自己 的 事务 策略 (如 , 针对 CORBA 的 事务 服务 ) 


Hibernate 的 一 些 特性 (比如 二 级 缓存 , Contextual Sessions with JTA 等 等 ) 需 要 访问 
在 托管 环境 中 的 JTA TransactionManager . 由 于 J2EE 没 有 标准 化 一 个 单一 的 机 
制 ,Hibernate 在 应 用 程序 服务 器 中 ， 你 必须 指定 Hibernate 如 何 获 

得 TransactionManager 的 引用 : 


表 3.10. JTA TransactionManagers 


org 


org. 


org. 


org. 


org. 


org. 


org 


org. 


org 


org. 


. hibernate. 


hibernate 


hibernate. 


hibernate. 


hibernate. 
hibernate. 
.hibernate. 
hibernate. 
„hibernate. 


hibernate. 


Transaction t/ #& 


transaction. 


.transaction 


transaction 


transaction 


transaction 


transaction. 
transaction. 
transaction. 
transaction. 


transaction. 


JBossTransactionManagerLookup 


.WeblogicTransactionManagerLookup 


.WebSphereTransact ionManagerLookup 
.WebSphereExtendedJTATransactionLookup 


.OrionTransactionManagerLookup 


ResinTransactionManagerLookup 
JOTMTransactionManagerLookup 

JOnASTransactionManagerLookup 
JRun4TransactionManagerLookup 


BESTransactionManagerLookup 


3.8.2. JNDI 绑 定 的 SessionFactory 


与 JNDI 绑 定 的 Hibernate 的 SessionFactory 能 简化 工厂 的 查询 ， 简 化 创建 新 
的 Session . 需要 注意 的 是 这 与 JNDI 绑 定 Datasource 没有 关系 , 它们 只 是 恰巧 
用 了 相同 的 注册 表 ! 


如 果 你 希望 将 SessionFactory 绑 定 到 一 个 JNDI 的 名 字 空 间 , 用 属 

性 hibernate.session_factory_name 指定 一 个 名 字 ( 如 ， 
java:hibernate/SessionFactory ). 如 果 不 设 置 这 个 属性 ， 

SessionFactory 将 不 会 被 绑 定 到 JNDI 中 . (在 以 只 读 JNDI| 为 默认 实现 的 环境 中 ， 
这 个 设置 尤其 有 用 , 如 Tomcat.) 


在 将 SessionFactory 绑 定 至 JNDI 时 , Hibernate 将 使 用 hibernate.jndi.url , 
和 hibernate.jndi.class 的 值 来 实例 化 初始 环境 (initial context). 如 果 它 们 没有 
被 指定 , 将 使 用 默认 的 Initialcontext . 


在 你 调用 cfg.buildSessionFactory() Æ, Hibernate 会 自动 

将 SessionFactory 注册 到 JNDI. 这 意味 这 你 至 少 需要 在 你 应 用 程序 的 启动 代码 
(或 工具 类 ) 中 完成 这 个 调用 , 除非 你 使 用 HibernateService 来 做 JMX 部 署 ( 见 后 
面 讨论 ) 


假若 你 使 用 JNDI SessionFactory ,EJB 或 者 任何 其 它 类 都 可 以 从 JNDI 中 找到 
此 SessionFactory 。 
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我 们 建议 ， 在 受 管 理 的 环境 中 ， 把 SessionFactory 绑 定 到 JNDI， 在 其 它 情况 

下 ， 使 用 一 个 static(# 8&4) singleton。 为 了 在 你 的 应 用 程序 代码 中 隐藏 这 些 细 
节 ， 我 们 还 建议 你 用 一 个 helper 类 把 实际 查找 SessionFactory 的 代码 隐藏 起 来 ， 
比如 HibernateUtil.getSessionFactory() 。 注 意 ， 这 个 类 也 就 可 以 方便 地 局 


大 


动 Hibernate， 参 见 第 一 章 。 


3.8.3. 在 JTA 环 境 下 使 用 Current Session context 
(当前 Session 上 下 文 ) 管 理 


在 Hibernate 中 ， 管 理 Session 和 transaction 最 好 的 方法 是 自动 的 " 当 

前 " Session 管理 。 请 参见 第 2.5 节 “ 上 下 文 相关 的 (Contextual) Session” 一 节 的 

讨论 。 使 用 "jta" session 上 下 文 ， 假 若 在 当前 JTA 事 务 中 还 没有 

Hibernate Session 关联 ， 第 一 次 sessionFactory.getCurrentSession() 调用 

会 启动 一 个 Session, 并 关联 到 当前 的 JTA 事 务 。 在 "jta" 上 下 文中 调 

用 getCurrentSession() 获得 的 Session ， 会 被 设置 为 在 transaction 关 闭 的 时 

候 自 动 flush (清洗 ) 、 在 transaction 关 闭 之 后 自动 关闭 ， 每 句 语句 之 后 主动 释放 

JDBC 连 接 。 这 就 可 以 根据 JTA 事 务 的 生命 周期 来 管理 与 之 关联 的 Session > AP 

代码 中 就 可 以 不 再 考虑 这 文 些 管理 。 你 的 代码 也 可 以 通过 UserTransaction 用 编程 
方式 使 用 JTA， 或 者 (我 们 建议 ， 为 了 便于 移植 代码 ) 使 用 Hibernate 

的 Transaction API 来 设置 transaction 边 界 。 如 果 你 的 代码 运行 在 EJB 容 器 中 ， 

建议 对 CMT 使 用 声明 式 事务 声明 。 


3.8.4. JMX 4 


为 了 将 SessionFactory 注册 到 JNDI 中 ， cfg.buildSessionFactory() 这 行 代 
码 仍 需 在 某 处 被 执行 . 你 可 在 一 个 static 初始 化 块 ( 像 Hibernateutil 中 的 那 
样 ) 中 执行 它 或 将 Hibernate 部 署 为 一 个 托管 的 服务 . 


为 了 部 署 在 一 个 支持 JMX 的 应 用 程序 服务 器 上 ，Hibernate 和 

org.hibernate. jmx.HibernateService 一 同 分 发 ， 如 Jboss AS。 实际 的 部 署 
和 配置 是 由 应 用 程序 服务 器 提供 者 指定 的 . 这 里 是 JBoss 4.0.x 

的 jboss-service.xml 样 例 : 


<?xml version="1.0"?> 
<server> 


<mbean code="org.hibernate. jmx.HibernateService" 
name="jboss.jca:service=HibernateFactory, name=HibernateFacto 
ry"> 


<1-- 必须 的 服务 --> 
<depends>jboss.jca:service=RARDeployer</depends> 
<depends>jboss.jca:service=LocalTxCM, name=HsqlDS</depends> 


<!-- 将 Hibernate 服 务 绑 定 到 JNDI --> 
<attribute name="JndiName">java: /hibernate/SessionFactory</a 
ttribute> 


<!-- 数据 源 设置 --> 

<attribute name="Datasource">java:HsqlDS</attribute> 

<attribute name="Dialect">org.hibernate.dialect .HSQLDialect< 
/attribute> 


<!-- 事务 集成 --> 
<attribute name="TransactionStrategy"> 
org.hibernate. transaction. JTATransactionFactory</attribu 
te> 
<attribute name="TransactionManagerLookupStrategy"> 
org. hibernate. transaction. JBossTransactionManagerLookup< 
/attribute> 
<attribute name="FlushBeforeCompletionEnabled">true</attribu 
te> 
<attribute name="AutoCloseSessionEnabled">true</attribute> 


<!-- 抓 取 选 项 --> 
<attribute name="MaximumFetchDepth">5</attribute> 


<1-- 二 级 缓存 --> 

<attribute name="SecondLevelCacheEnabled">true</attribute> 

<attribute name="CacheProviderClass">org.hibernate.cache.EhC 
acheProvider</attribute> 

<attribute name="QueryCacheEnabled">true</attribute> 


ues Mey Gar 
<attribute name="ShowSqlEnabled">true</attribute> 


<!-- 映射 定义 文件 --> 
<attribute name="MapResources">auction/Item.hbm.xml,auction/ 
Category .hbm. xml</attribute> 


</mbean> 


</server> 


这 个 文件 是 部 署 在 META-INF 目录 下 的 , 并 会 被 打包 到 以 .sar (service archive) 
为 扩展 名 的 JAR 文 件 中 . 同时 ， 你 需要 将 Hibernate、 它 所 需要 的 第 三 方 库 、 你 编译 
好 的 持久 化 类 以 及 你 的 映射 定义 文件 打包 进 同 一 个 文档 . 你 的 企业 Bean( 一 般 为 会 话 
Bean) 可 能 会 被 打包 成 它们 自己 的 JAR 文 件 , 但 你 也 许 会 将 EJB JAR 文 件 一 同 包 含 进 
能 独立 ( 热 ) 部 署 的 主 服务 文档 . 参考 JBoss AS 文档 以 了 解 更 多 的 JMX 服 务 与 EJB 部 署 
的 信息 . 
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4.1. 一 个 简单 的 POJO 例 子 
大 多 数 Java 程 序 需 要 用 一 个 持久 化 类 来 表示 猫 科 动物 。 


package eg; 
import java.util.Set; 
import java.util.Date; 


public class Cat { 
private Long id; // identifier 


private Date birthdate; 
private Color color; 
private char sex; 
private float weight; 
private int litterId; 


private Cat mother; 
private Set kittens = new HashSet(); 


private void setId(Long id) { 
this .id=id; 
} 


public Long getId() { 
return id; 

} 

void setBirthdate(Date date) { 
birthdate = date; 

} 

public Date getBirthdate() { 
return birthdate; 

} 

void setWeight(float weight) { 
this.weight = weight; 

} 

public float getWeight() { 
return weight; 

} 

public Color getColor() { 
return color; 

} 

void setColor(Color color) { 


this.color = color; 
} 


void setSex(char sex) { 


this.sex=sex; 


} 
public char getSex() { 


return sex; 
} 


void setLitterId(int id) { 
this.litterId = id; 
} 


public int getLitterId() { 
return litterId; 
} 


void setMother(Cat mother) { 
this.mother = mother; 
} 


public Cat getMother() { 
return mother; 
} 


void setKittens(Set kittens) { 
this.kittens = kittens; 


public Set getKittens() { 
return kittens; 
} 


// addKitten not needed by Hibernate 

public void addKitten(Cat kitten) { 
kitten.setMother(this); 

kitten.setLitterId( kittens.size() ); 
kittens.add(kitten); 

} 


这 里 要 遵循 四 条 主要 的 规则 : 


4.1.1. 实现 一 个 默认 的 〈 即 无 参数 的 ) 构造 方法 
(constructor ) 


Cat 有 一 个 无 参数 的 构造 方法 。 所 有 的 持久 化 类 都 必须 有 一 个 默认 的 构造 方法 
(可 以 不 是 public 的 ) ， 这 样 的 话 Hibernate 就 可 以 使 用 
Constructor.newInstance() 来 实例 化 它们 。 我 们 强烈 建议 ， 在 Hibernate 中 ， 
为 了 运行 期 代理 的 生成 ， 构 造 方法 至 少 是 包 (package) 内 可 见 的 。 


4.1.2. 提供 一 个 标识 属性 (identifier property ) 
(可 选 ) 


Cat 有 一 个 属性 叫做 id 。 这 个 属性 映射 数据 库 表 的 主键 字段 。 这 个 属性 可 以 叫 
任何 名 字 ， 其 类 型 可 以 是 任何 的 原始 类 型 、 原 始 类 型 的 包装 类 型 、 
java.lang.String 或 者 是 java.util.Date 。 (如 果 你 的 遗留 数据 库 表 有 联 
合 主 键 ， 你 甚至 可 以 用 一 个 用 户 自 定义 的 类 ， 该 类 拥有 这 些 类 型 的 属性 。 参 见 后 面 
的 关于 联合 标识 符 的 章节 。 ) 


标识 符 属 性 是 可 选 的 。 可 以 不 用 管 它 ， 让 Hibernate 内 部 来 追踪 对 象 的 识别 。 但 是 
我 们 并 不 推荐 这 样 做 。 
实际 上 ， 一 些 功 能 只 对 那些 声明 了 标识 符 属性 的 类 起 作用 : 
o 托管 对 象 的 传播 性 再 连接 (级 联 和 更 新 或 级 联合 并 ) 
播 性 持久 化 (transitive persistence)” 
e Session.saveOrUpdate( ) 


参阅 + 第 10.11 节 “ 传 





e Session,merge() 


我 们 建议 你 对 持久 化 类 声明 命名 一 致 的 标识 属性 。 我 们 还 建议 你 使 用 一 个 可 以 为 空 
(也 就 是 说 ， 不 是 原始 类 型 ) 的 类 型 。 


4.1.3. 使 用 非 final 的 类 (可 选 ) 


代理 (proxies) 是 Hibernate 的 一 个 重要 的 功能 ， 它 依赖 的 条 件 是 ， 持 久 化 类 或 者 
是 非 final 的 ， 或 者 是 实现 了 一 个 所 有 方法 都 声明 为 public 的 接口 。 


你 可 以 用 Hibernate 持 久 化 一 个 没有 实现 任何 接口 的 final 类 ， 但 是 你 不 能 使 用 代 
理 来 延迟 关联 加 载 ， 这 会 限制 你 进行 性 能 优化 的 选择 。 


你 也 应 该 避免 在 非 final 类 中 声明 public final 的 方法 。 如 果 你 想 使 用 一 个 
有 public final 方法 的 类 ， 你 必须 通过 设置 lazy="false" 来 明确 地 禁用 代 
I o 


11 .4. 为 持久 化 字段 声明 访问 器 (accessors) 和 是 否 
可 变 的 标志 (mutators)( 可 选 ) 


Cat 为 它 的 所 有 持久 化 字段 声明 了 访问 方法 。 很 多 其 他 ORM 工 具 直 接 对 实例 变量 
进行 持久 化 。 我 们 相信 ， 在 关系 数据 库 Schema 和 类 的 内 部 数据 结构 之 间 引 入 间接 
层 (原文 为 " 非 直 接 "，indirection) 会 好 一 些 。 默 认 情 况 下 Hibernate 持 久 化 JavaBeans 
风格 的 属性 ， 认 可 getFoo ， isFoo 和 setFoo 这 种 形式 的 方法 名 。 如 果 需 
要 ， 你 可 以 对 某 些 特定 属性 实行 直接 字段 访问 。 


属性 不 需要 要 声明 为 public 的 。Hibernate 可 以 持久 化 一 个 有 
default ` protected 或 private 的 get/set 方 法 对 的 属性 进行 持久 化 。 


TODO : property 和 proxy 包 里 的 用 户 扩展 框架 文档 。 


4.2. 实现 继承 (Inheritance) 
子 类 也 必须 遵守 第 一 条 和 第 二 条 规则 。 它 从 超 类 cat 继承 了 标识 属性 。 


package eg; 


public class DomesticCat extends Cat { 
private String name; 


public String getName() { 
return name; 


protected void setName(String name) { 
this .name=name; 
} 


4.3. 实现 equals() 和 hashCode() 


如 果 你 有 如 下 需求 ， 你 必须 重 载 equals() 和 hashCode() 方法 : 
o 想 把 持久 类 的 实例 放 入 Set 中 ( 当 表 示 多 值 关联 时 ， 推 荐 这 么 做 ) 
eo 想 重 用 脱 管 实例 


Hibernate 保 证 ， 仅 在 特定 会 话 范 围 内 ， 持 久 化 标识 (数据 库 的 行 ) 和 Java 标 识 是 
等 价 的 。 因 此 ， 一 旦 我 们 混合 了 从 不 同 会 话 中 获取 的 实例 ， 如 果 希 望 set 有 明确 
的 语义 ， 就 必须 实现 equals() 和 hashCode() ° 


实现 equals() / hashCode() 最 显而易见 的 方法 是 比较 两 个 对 象 标识 符 的 值 。 如 
果 值 相同 ， 则 两 个 对 象 对 应 于 数据 库 的 同一 行 ， 因 此 它们 是 相等 的 (如果 都 被 添加 
到 Set ， 则 在 set 中 只 有 一 个 元 素 ) 。 不 幸 的 是 ， 对 生成 的 标识 不 能 使 用 这 种 
方法 。Hibernate 仅 对 那些 持久 化 对 象 赋 标 识 值 ， 一 个 新 创建 的 实例 将 不 会 有 任何 标 
识 值 。 此 外 ， 如 果 一 个 实例 没有 被 保存 (unsaved)， 并 且 它 当前 正在 一 个 Set 中 ， 
保存 它 将 会 给 这 个 对 象 赋 一 个 标识 值 。 如 果 equals() 和 hashCode() 是 基于 
标识 值 实现 的 ， 则 其 哈 希 码 将 会 改变 ， 这 违反 了 set 的 契约 。 建 议 去 Hibernate 的 
站 点 阅读 关于 这 个 问题 的 全 部 讨论 。 注 意 ， 这 不 是 Hibernate 的 问题 ， 而 是 一 般 的 
Java 对 象 标识 和 Java 对 象 等 价 的 语义 问题 。 


我 们 建议 使 用 业务 键 值 相等 (Business key equality) k KHL equals() 和 
hashCode() 。 业 务 键 值 相等 的 意思 是 ， equals() 方法 仅仅 比较 形成 业务 键 的 
属性 ， 它 能 在 现实 世界 里 标识 我 们 的 实例 (是 一 个 自然 的 候选 码 ) 。 


public class Cat { 


public boolean equals(Object other) { 


if (this == other) return true; 
if ( !(other instanceof Cat) ) return false; 


final Cat cat = (Cat) other; 
if ( !cat.getLitterId().equals( getLitterId() ) ) return 


if ( !cat.getMother().equals( getMother() ) ) return fal 


return true; 


public int hashCode() { 


int result; 

result = getMother().hashCode(); 
result = 29 * result + getLitterId(); 
return result; 


注意 ， 业 务 键 不 必 像 数据 库 的 主键 那样 固定 不 变 (参见 第 11.1.3 节 “ 关 注 对 象 标识 
(Considering object identity)”) 。 对 业务 键 而 言 ， 不 可 变 或 唯一 的 属性 是 不 错 的 选 


择 。 


A %& 4% 7 (Dynamic models) 


注意 ， 以 下 特性 在 当前 处 于 试验 阶段 ， 将 来 可 能 会 有 变化 。 


运行 期 的 持久 化 实体 没有 必要 一 定 表 示 为 像 POJO 类 或 JavaBean 对 象 那 样 的 形式 。 
Hibernate 也 支持 动态 模型 (在 运行 期 使 用 Map 的 Map ) 和 象 DOM4J 的 树 模型 那 
样 的 实体 表示 。 使 用 这 种 方法 ， 你 不 用 写 持 久 化 类 ， 只 写 映 射 文件 就 行 了 。 


Hibernate 默 认 工作 在 普通 POJO 模 式 。 你 可 以 使 用 配置 选 
项 default_entity_mode ， 对 特定 的 SessionFactory ， 设 置 一 个 默认 的 实体 
表示 模式 。 (FMA 3.3“ Hibernate 配 置 属性 ”。) 


TRÆR Map 来 表示 的 例子 。 首 先 ， 在 映射 文件 中 ， 要 声明 entity-name 来 代 
替 一 个 类 名 (或 作为 一 种 附属 ) 。 


<hibernate-mapping> 
<class entity-name="Customer'"> 


<id name="id" 

type="long" 

column="ID"> 

<generator class="Ssequence"/> 
</id> 


<property name="name" 
column="NAME" 
type="string"/> 


<property name="address" 
column="ADDRESS" 
type="string"/> 


<many-to-one name="organization" 
column="ORGANIZATION_ID" 
class="0rganization"/> 


<bag name="orders" 
inverse="true" 
lazy="false" 
cascade="all"> 
<key column="CUSTOMER_ID"/> 
<one-to-many class="Order"/> 
</bag> 


</class> 


</hibernate-mapping> 


注意 ， 虽 然 是 用 目标 类 名 来 声明 关联 的 ， 但 是 关联 的 目标 类 型 除了 是 POJO 之 外 ， 
也 可 以 是 一 个 动态 的 实体 。 


在 使 用 dynamic-map A SessionFactory 设置 了 默认 的 实体 模式 之 后 ， 可 以 在 
运行 期 使 用 Map 的 Map ° 


Session s = openSession(); 
Transaction tx = s.beginTransaction(); 
Session s = openSession(); 


// Create a customer 
Map david = new HashMap(); 
david.put("name", "David"); 


// Create an organization 
Map foobar = new HashMap(); 
foobar.put("name", "Foobar Inc."); 


// Link both 
david.put("organization", foobar); 


// Save both 
s.save( "Customer", david); 
s.save( "Organization", foobar); 


tx.commit(); 
s.close(); 


动态 映射 的 好 处 是 ， 变 化 所 需要 的 时 间 少 了 ， 因 为 原型 不 需要 实现 实体 类 。 然 而 ， 
你 无 法 进行 编译 期 的 类 型 检查 ， 并 可 能 由 此 会 处 理 很 多 的 运行 期 异常 。 幸 亏 有 了 
Hibernate 映 射 ， 它 使 得 数 据 库 的 Schema 能 容易 的 规格 化 和 合理 化 ， 并 允许 稍 后 在 
此 之 上 添加 合适 的 领域 模型 实现 。 


实体 表示 模式 也 能 在 每 个 Session 的 基础 上 设置 : 


Session dynamicSession = pojoSession.getSession(EntityMode.MAP) ; 


// Create a customer 

Map david = new HashMap(); 
david.put("name", "David"); 
dynamicSession.save("Customer", david); 


dynamicSession.flush(); 
dynamicSession.close() 


// Continue on pojoSession 


请 注意 ， 用 EntityMode 调用 getSession() 是 在 Session 的 API 中 ， 而 不 

是 SessionFactory ° 这 样 ， 新 的 Session 共享 底层 的 JDBC 连 接 ， 事 务 ， 和 其 
他 的 上 下 文 信 息 。 这 意味 着 ， 你 不 需要 在 第 二 个 Session 中 调用 

flush() 和 close() ， 同 样 的 ， 把 事务 和 连接 的 处 理 交 给 原来 的 工作 单元 。 


关于 XML 表示 能 力 的 更 多 信息 可 以 在 第 18 章 XML 映射 中 找到 。 


4.5. 元 组 片断 映射 (Tuplizers) 


org.hibernate.tuple.Tuplizer ， 以 及 其 子 接口 ， 负 责 根据 给 定 

的 org.hibernate.EntityMode ， 来 复 现 片断 数据 。 如 果 给 定 的 片断 数据 被 认为 
其 是 一 种 数据 结构 ，"tuplizer" 就 是 一 个 知道 如 何 创 建 这 样 的 数据 结构 ， 以 及 如 何 给 
这 个 数据 结构 赋值 的 东西 。 比 如 说 ， 对 于 POJO 这 种 Entity Mode， 对 应 的 tuplizer 知 
道 通 过 其 构造 方法 来 创建 一 个 POJO， 再 通过 其 属性 访问 器 来 访问 POJO 属 性 。 有 
两 大 类 高 层 Tuplizer， 分 别 是 org.hibernate.tuple.entity.EntityTuplizer 
和 org.hibernate.tuple.entity.ComponentTuplizer 接 

Wo EntityTuplizer 负责 管理 上 面 提 到 的 实体 的 契约 ， 

而 ComponentTuplizer 则 是 针对 组 件 的 。 


用 户 也 可 以 插入 其 自 定义 的 tuplizer。 或 许 您 需要 一 种 不 同 于 dynamic-map entity- 
mode 中 使 用 的 java.util.HashMap 的 java.util.Map 实现 ; 或 许 您 需要 与 默 
认 策 略 不 同 的 代理 生成 策略 (proxy generation strategy)。 通 过 自 定 义 tuplizer 实 现 ， 
这 两 个 目标 您 都 可 以 达到 。Tuplizer 定 义 被 附加 到 它们 期 望 管理 的 entity 或 者 
component 映 射 中 。 回 到 我 们 的 customer entity 例 子 : 


<hibernate-mapping> 
<class entity-name="Customer"> 

<!-- 
Override the dynamic-map entity-mode 
tuplizer for the customer entity 

T 

<tuplizer entity-mode="dynamic-map" 

class="CustomMapTuplizerImp1"/> 


<id name="id" type="long" column="ID"> 
<generator class="sequence"/> 
</id> 


<!-- other properties --> 
</class> 
</hibernate-mapping> 
public class CustomMapTuplizeriImpl 
extends org.hibernate.tuple.entity.DynamicMapEntityTupli 
zer { 
// override the buildInstantiator() method to plug in our cu 
stom map... 
protected final Instantiator buildInstantiator ( 
org.hibernate.mapping.PersistentClass mappingInfo) { 
return new CustomMapInstantiator( mappingInfo ); 


} 


private static final class CustomMapInstantiator 
extends org.hibernate.tuple.DynamicMapInstantitor { 
// override the generateMap() method to return our custo 
m map... 
protected final Map generateMap() { 
return new CustomMap(); 
} 
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5.1. 映射 定义 (Mapping declaration ) 


对 象 和 关系 数据 库 之 间 的 映射 通常 是 用 一 个 XML 文档 (XML document) 来 定义 的 。 
这 个 映射 文档 被 设计 为 易 读 的 ， 并 且 可 以 手工 修改 。 了 映射 语言 是 以 Java 为 中 心 ， 这 
意味 着 映射 文档 是 按照 持久 化 类 的 定义 来 创建 的 ， 而 非 表 的 定义 。 


请 注意 ， 虽 然 很 多 Hibernate 用 户 选择 手写 XML 映 射 文档 ， 但 也 有 一 些 工 具 可 以 用 来 
生成 映射 文档 ， 包 括 XDoclet,Middlegen 和 AndroMDA ° 


让 我 们 从 一 个 映射 的 例子 开始 : 


<?xml version="1.0"?> 
<!DOCTYPE hibernate-mapping PUBLIC 
"-//Hibernate/Hibernate Mapping DTD 3.0//EN" 
"http://hibernate.sourceforge.net/hibernate-mapping-3. 
0.dtd"> 


<hibernate-mapping package="eg"> 


<class name="Cat" 
table="cats" 
discriminator -value="C"> 


<id name="id"> 
<generator class="native"/> 
</id> 


<discriminator column="subclass" 
type="Character"/> 


<property name="weight"/> 


<property name="birthdate" 
type="date" 
not-null="true" 
update="false"/> 


<property name="color" 
type="eg.types.ColorUserType" 
not-null="true" 
update="false"/> 


<property name="sex" 
not-null="true" 
update="false"/> 


<property name="litterId" 
column="litterId" 
update="false"/> 


<many-to-one name="mother" 
column="mother_id" 
update="false"/> 


<set name="kittens" 
inverse="true" 
order -by="litter_id"> 
<key column="mother_id"/> 
<one-to-many class="Cat"/> 
</set> 


<subclass name="DomesticCat" 
discriminator -value="D"> 


<property name="name" 
type="string"/> 


</subclass> 
</class> 
<class name="Dog"> 
<!-- mapping for Dog could go here --> 
</class> 
</hibernate-mapping> 
我 们 现在 开始 讨论 映射 文档 的 内 容 。 我 们 只 描述 Hibernate 在 运行 时 用 到 的 文档 元 素 


和 属性 。 了 上 映射 文档 还 包括 一 些 额 外 的 可 选 属性 和 元 素 ， 它 们 在 使 用 Schema 导出 工 
具 的 时 候 会 影响 导出 的 数据 库 schema 结 果 。 (上 比如， not-null 属性 。) 


5.1.1. Doctype 


所 有 的 XML 映射 都 需要 定义 如 上 所 示 的 doctype。DTD 可 以 从 上 述 URL 中 获取 ， 也 
可 以 从 hibernate-x.x.x/src/net/sf/hibernate 目录 中 、 

或 hibernate.jar 文件 中 找到 。Hibernate 总 是 会 首先 在 它 的 classptah 中 搜索 
DTD 文 件 。 如 果 你 发 现 它 是 通过 连接 Internet 查 找 DTD 文 件 ， 就 对 照 你 的 classpath 
目录 检查 XML 文件 里 的 DTD 声 明 。 


5.1.1.1. EntityResolver 


As mentioned previously, Hibernate will first attempt to resolve DTDs in its 
classpath. The manner in which it does this is by registering a custom 

org.xml.sax.EntityResolver implementation with the SAXReader it uses to 
read in the xml files. This custom EntityResolver recognizes two different 
systemld namespaces. 如 前 所 述 ,Hibernate 首 先 在 其 classpath 中 查找 DTD。 其 行为 
是 依靠 在 系统 中 注册 的 org.xml.sax.EntityResolver 的 一 个 具体 实现 ， 
SAXReader 依 靠 它 来 读 取 xml 文 件 。 这 一 EntityResolver 实现 能 辨认 两 种 不 同 
的 systenld 命 名 空间 。 


e 若 resolver 遇 到 了 一 个 以 http://hibernate.sourceforge.net/ 为 开头 的 
systemld， 它 会 辨认 出 是 hibernate namespace ，resolver 就 试图 通过 加 载 
Hibernate 类 的 classloader 来 查找 这 些 实体 。 


e 若 resolver 遇 到 了 一 个 使 用 classpath:// URL 协 议 的 Systemld， 它 会 辨认 出 
这 是 user namespace ,resolver 试 图 通过 (1) 当 前 线程 上 下 文 的 classloader 和 
(2) 加 载 Hibernate class 的 classloader 来 查找 这 些 实体 。 


使 用 user namespace( 用 户 命名 空间 ) 的 例子 : 


<?xml version="1.0"?> 
<!DOCTYPE hibernate-mapping PUBLIC 
"-//Hibernate/Hibernate Mapping DTD 3.0//EN" 
"http://hibernate.sourceforge.net/hibernate-mapping-3.0. 
didi | 
<!ENTITY types SYSTEM "classpath://your/domain/types. xmL"> 
] > 


<hibernate-mapping package="your .domain"> 
<class name="MyEntity"> 
<id name="id" type="my-custom-id-type"> 


</id> 
<class> 
&types,; 
</hibernate-mapping> 


types.xml 是 your.domain 包 中 的 一 个 资源 ， 它 包含 了 一 个 定制 的 第 5.2.3 7 
“ 自 定 义 值 类 型 ”。 


5.1.2. hibernate-mapping 


这 个 元 素 包 括 一 些 可 选 的 属性 。 schema 和 catalog 属性 ， 指 明了 这 个 映射 所 连 
接 (refer) 的 表 所 在 的 Schema 和 /或 catalog 名 称 。 假若 指定 了 这 个 属性 ， 表 名 会 加 
上 所 指定 的 Schema 和 catalog 的 名 字 扩 展 为 全 限定 名 。 假 若 没 有 指定 ， 表 名 就 不 会 
使 用 全 限定 名 。 default-cascade 指定 了 未 明确 注 明 cascade 属性 的 Java 属 性 
和 采取 什么 样 的 默认 级 联 风格 。 auto-import 属性 默认 让 我 
们 在 查询 语言 中 可 以 使 用 非 全 限定 名 的 类 名 。 


<hibernate-mapping 
schema="schemaName" 
catalog="catalogName" 
default -cascade="cascade_style" 
default -access="field|property|ClassName" 
default -lazy="true| false" 
auto-import="true|false" 
package="package.name" 

/> 


@ schema (* x): 数据 库 schema 的 名 称 。 
@ catalog (可 选 ): 数据 库 catalog 的 名 称 。 
© default-cascade (可 选 -默认 为 none ): 默认 的 级 联 风格 。 


default-access | Ms 默认 为 property ): Hibernate 用 来 访问 所 有 属 
性 的 策略 。 可 以 通过 实现 PropertyAccessor 接口 自 定 义 。 


default-lazy (可 选 -默认 为 true ) 指定 了 未 明确 注 明 lazy 属性 的 
Java% ltf RAX > Hibernate 会 采取 什么 样 的 默认 加 载 风格 。 
auto-import (可 选 - 默认 为 true ): 指定 我 们 是 否 可 以 在 查询 语言 中 使 
用 非 全 限定 的 类 名 TRON) i 


package (T2): 指定 一 个 包 前 级 ， 如 果 在 映射 文档 中 没有 指定 全 限定 的 类 
名 ， 就 使 用 这 个 作为 包 名 。 


Q 


假若 你 有 两 个 持久 化 类 ， 它 们 的 非 全 限定 名 是 一 样 的 (就 是 两 个 类 的 名 字 一 样 ， 所 
在 的 包 不 一 样 -- 译 者 注 ) ， 你 应 该 设置 auto-import="false" 。 6 
个 “import 过 ”的 名 字 同 时 对 应 两 个 类 ，Hibernate 会 抛 出 一 个 异常 


注意 hibernate-mapping 元 素 允许 你 谋 套 多 个 如 上 所 示 的 &lt;class&gt; 映 
射 。 但 是 最 好 的 做 法 (也 许 一 些 工具 需要 的 ) 是 一 个 持久 化 类 (或 一 个 类 的 继承 层 
次 ) 对 应 一 个 映射 文件 ， 并 以 持久 化 的 超 类 名 称 命名 ， 例 如 : Cat.hbm.xml ， 
Dog.hbm.xml ， 或 者 如 果 使 用 继承 ， Animal.hbm.xml ° 


5.1. 映射 定义 (Mapping declaration ) 
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5.1.3. 


class 


你 可 以 使 用 class 元 素来 定义 一 个 持久 化 类 : 


<class 


/> 


name="ClassName" 

table="tableName" 

discriminator -value="discriminator_value" 
mutable="true|false" 

schema="owner" 

catalog="catalog" 
proxy="ProxyInter face" 

dynamic -update="true|false" 

dynamic -insert="true|false" 
select-before-update="true|false" 
polymorphism="implicit |explicit" 
where="arbitrary sql where condition" 
persister="PersisterClass" 
batch-size="N" 
optimistic-lock="none|version|dirty|all" 
lazy="true|false" 
entity-name="EntityName" 
check="arbitrary sql check condition" 
rowid="rowid" 

subselect="SQL expression" 
abstract="true|false" 

node="element -name" 


name (可 选 ): 持久 化 类 (或 者 接口 ) 的 Java 全 限定 名 。 如 果 这 个 属性 
不 存在 ，Hibernate 将 假定 这 是 一 个 非 POJO 的 实体 映射 。 

table (可 选 - 默认 是 类 的 非 全 限定 名 ): 对 应 的 数据 库 表 名 。 
discriminator-value (可 选 - 默认 和 类 名 一 样 ): 一 个 用 于 区 分 不 同 
的 子 类 的 值 ， 在 多 态 行为 时 使 用 。 它 可 以 接受 的 值 包括 null 和 

Ne Cael 2 


mutable (可 选 ， 默 认 值 为 true ) 表明 该 类 的 实例 是 可 变 的 或 者 不 可 


变 的 。 


schema (可 选 ): R&R &lt;hibernate-mapping&gt; 元 素 中 指定 
的 Schema 名 字 。 


catalog (可 选 ): 履 盖 在 根 &lt;hibernate-mapping&gt; 元 素 中 指 
定 的 catalog 名 字 。 


proxy (可 选 ) 指定 一 个 接口 ， 在 延迟 装载 时 作为 代理 使 用 。 你 可 以 在 


(17) 


(18) 


(19) 


(20) 


这 里 使 用 该 类 自己 的 名 字 。 


dynamic-update (可 选 , 默认 为 false ): 指定 用 于 UPDATE 的 SQL 
将 会 在 运行 时 动态 生成 ， 并 且 只 更 新 那些 改变 过 的 字段 。 


dynamic-insert (可 选 , 默认 为 ”false ): 指定 用 于 INSERT 的 SQL 
将 会 在 运行 时 动态 生成 ， 并 且 只 包含 那些 非 空 值 字段 。 


select-before-update (可 选 , 默认 为 false ): 指定 Hibernate 除 非 

确定 对 象 在 正 被 修改 了 (如 果 该 值 为 true 一 译注 ) ， 否 则 不 会 执行 SQL 
UPDATE 操作 。 在 特定 场合 (实际 上 ， 它 只 在 一 个 瞬时 对 象 (transient 
object) 关联 到 一 个 新 的 session 中 时 执行 的 update() 中 生效 ) ， 这 说 明 
Hibernate 会 在 UPDATE 之 前 执行 一 次 额外 的 SQL SELECT 操作 ， 来 决 
定 是 否 应 该 执行 UPDATE ° 


polymorphism (多 态 ) (可 选 , 默认 值 为 implicit ( 隐 式 ) ): 界定 是 
隐 式 还 是 显 式 的 使 用 多 态 查 询 (这 只 在 Hibernate 的 具体 表 继 承 策略 中 用 
到 一 译注 ) 。 

where (可 选 ) 指定 一 个 附加 的 SQL WHERE 条件， 在 抓 取 这 个 类 的 对 
象 时 会 一 直 增 加 这 个 条 件 。 


persister (可 选 ): 指定 一 个 定制 的 ClassPersister ° 


batch-size (可 选 ,默认 是 1 ) 指定 一 个 用 于 根据 标识 符 (identifier) 
抓 取 实例 时 使 用 的 "batch size"( 批 次 抓 取 数量 ) © 


optimistic-lock (乐观 锁定 ) (可 选 ， 默 认 是 version ): 决定 乐观 
锁定 的 策略 。 


lazy (可 选 ): 通过 设置 lazy="false" ， 所 有 的 延迟 加 载 (Lazy 
fetching) 功能 将 被 全 部 禁用 (disabled) ° 


entity-name (可 选 ， 默 认为 类 名 ): Hibernate3 允 许 一 个 类 进行 多 次 映 
Ht ( 前 提 是 映射 到 不 同 的 表 ) ， 并 且 人 允许 使 用 Maps 或 XML 代替 Java 层 
次 的 实体 映射 (也 就 是 实现 动态 领域 模型 ， 不 用 写 持 久 化 类 一 译注 ) 。 
更 多 信息 请 看 第 4.4 节 “ 动 态 模 型 (Dynamic models)’ and 第 18 章 XML 
映射 。 


check (可 选 ): 这 是 一 个 SQL 表 达 式 ， 用 于 为 自动 生成 的 schema 添 加 
多 行 (multi-row) 约束 检查 。 


rowid (可 选 ) Hibernate 可 以 使 用 数据 库 支持 的 所 谓 的 ROWIDs， 例 
如 : Oracle 数 据 库 ， 如 果 你 设置 这 个 可 选 的 rowid > Hibernate 可 以 
使 用 额外 的 字段 rowid 实现 快速 更 新 。ROWID 是 这 个 功能 实现 的 重 
点 ， 它 代表 了 一 个 存储 元 组 (tuple) 的 物理 位 置 。 


subselect (可 选 ): 它 将 一 个 不 可 变 (immutable) 并 且 只 读 的 实体 映 
射 到 一 个 数据 库 的 子 查询 中 。 当 你 想 用 视图 代替 一 张 基本 表 的 时 候 ， 这 
是 有 用 的 ， 但 最 好 不 要 这 样 做 。 更 多 的 介绍 请 看 下 面 内 容 。 


abstract (可 选 ): 用 于 在 &lt;union-subclass&gt; 的 继承 结构 


(hierarchies) 中 标识 抽象 超 类 。 


若 指 明 的 持久 化 类 实际 上 是 一 个 接口 ， 这 也 是 完全 可 以 接受 的 。 之 后 你 可 以 用 元 
素 @lt;subclass&gt; 来 指定 该 接口 的 实际 实现 类 。 你 可 以 持久 化 任何 static ( 
态 的 ) 内 部 类 。 你 应 该 使 用 标准 的 类 名 格式 来 指定 类 名 ， 比如 : Foo$Bar 。 


不 可 变 类 ， mutable="false" 不 可 以 被 应 用 程序 更 新 或 者 删除 。 这 可 以 让 
Hibernate 做 一 些小 小 的 性 能 优化 。 


可 选 的 proxy 属性 允许 延迟 加 载 类 的 持久 化 实例 。 Hibernate 开 始 会 返回 实现 了 这 
个 命名 接口 的 CGLIB 代 理 。 当 代理 的 某 个 方法 被 实际 调用 的 时 候 ， 蜂 实 的 持久 化 对 
象 才 会 被 装载 。 参 见 下 面 的 “用 于 延迟 装载 的 代理 ”。 


Implicit ( 隐 式 ) 的 多 态 是 指 ， 如 果 查 询 时 给 出 的 是 任何 超 类 、 该 类 实现 的 接口 或 者 该 

类 的 名 字 ， ‘cme eee 如 果 查 询 中 给 出 的 是 子 类 的 名 字 ， 则 会 返回 子 

类 的 实例 。 Explicit ( 显 式 ) 的 多 态 是 指 ， 只 有 在 查询 时 给 出 明确 的 该 类 名 字 时 才 

会 返回 这 个 类 的 实例 ; ， &lt;class&gt; 的 定义 中 作 

为 &lt;subclass&gt; 或 者 &lt;joined-subclass&gt; 出 现 的 子 类 ， 才 会 可 能 

ae 在 大 多 数 情况 下 ， 默 认 的 polymorphism="implicit" 都 是 合适 的 。 BX 
多 态 在 有 两 个 不 同 的 类 映射 到 同一 个 表 的 时 候 很 有 用 。 (允许 一 个 “轻型 "的 类 ， 

se 分 表 字 段 ) 。 


persister 属性 可 以 让 你 定制 这 个 类 使 用 的 持久 化 策略 。 你 可 以 指定 你 自己 实现 
org.hibernate.persister.EntityPersister 的 子 类 ， 你 甚至 可 以 完全 从 头 开 
始 编写 一 个 org.hibernate.persister.ClassPersister 接口 的 实现 ， 比如 是 
用 储存 过 程 调用 、 序 列 化 到 文件 或 者 LDAP 数 据 库 来 实现 。 参 

阅 org.hibernate.test.CustomPersister ， 这 是 一 个 简单 的 例子 (“持久 化 ”到 
一 个 Hashtable ) œ 


请 注意 dynamic-update 和 dynamic-insert 的 设置 并 不 会 继承 到 子 类 ， 所 以 
在 &lt;subclass&gt; 或 者 &lt;joined-subclass&gt; 元 素 中 可 能 需要 再 次 设 
置 。 这 些 设 置 是 否 能 够 提高 效率 要 视 情 形 而 定 。 请 用 你 的 智慧 决定 是 否 使 用 。 


使 用 select-before-update 通常 会 降低 性 能 。 如 果 你 重新 连接 一 个 脱 管 
(detache) 对 象 实例 到 一 个 Session 中 时 ， 它 可 以 防止 数据 库 不 必要 的 触发 
update 。 这 就 很 有 用 了 。 


如 果 你 打开 了 dynamic-update ， 你 可 以 选择 几 种 乐观 锁定 的 策略 : 
e version (版 本 检查 ) 检查 version/timestamp 字 段 
。 all (全 部 ) ”检查 全 部 字段 
e dirty ( 脏 检查 ) 只 检察 修改 过 的 字段 
e none (不 检查 ) 不 使 用 乐观 锁定 
我 们 非常 强烈 建议 你 在 Hibernate 中 使 用 version/timestamp 字 段 来 进行 乐观 锁定 。 


对 性 能 来 说 ， 这 是 最 好 的 选择 ， 并 且 这 也 是 唯一 能 够 处 理 在 Session 外 进行 操作 的 策 
略 (例如 : 在 使 用 Session,merge() 的 时 候 ) 。 


对 Hibernate 映 射 来 说 视图 和 表 是 没有 区 别 的 ， 这 是 因为 它们 在 数据 层 都 是 透明 的 ( 
注意 : 一 些 数据 库 不 支持 视图 属性 ， 特 别 是 更 新 的 时 候 ) 。 有 时 你 想 使 用 视图 ， 但 
却 不 能 在 数据 库 中 创建 它 ( 例 如 :在 遗留 的 Schema 中 ) 。 这 样 的 话 ， 你 可 以 映射 
一 个 不 可 变 的 (immutable) 并 且 是 只 读 的 实体 到 一 个 给 定 的 SQL 子 查询 表达 式 : 


<class name="Summary"> 

<subselect> 
select item.name, max(bid.amount), count(*) 
from item 
join bid on bid.item_id = item.id 
group by item.name 

</subselect> 

<synchronize table="item"/> 

<synchronize table="bid"/> 

<id name="name"/> 


</class> 
定义 这 个 实体 用 到 的 表 为 同步 (synchronize) ， 确 保 自动 刷新 (auto-flush) 正确 


执行 ， 并且 依赖 原 实 体 的 查询 不 会 返回 过 期 数据 。 alt;subselectagt; 在 属性 
元 素 和 一 个 谋 套 映射 元 素 中 都 可 见 。 


5.1.4. id 


被 映射 的 类 必须 定义 对 应 数据 库 表 主键 字段 。 大 多 数 类 有 一 个 JavaBeans 风 格 的 属 
性 ， 为 每 一 个 实例 包含 唯一 的 标识 。 &1t;id&gt; 元 素 定 义 了 该 属性 到 数据 库 表 
主键 字段 的 映射 。 


<id 
name="propertyName" 
type="typename" 
column="column_name" 
unsaved -value="null1|any|none| undefined |id_value" 
access="field|property|ClassName" 
node="element -name|@attribute-name|element/@attribute|." 
> 
<generator class="generatorClass"/> 
</id> 


© name (可 选 ): 标识 属性 的 名 字 。 
@ type (可 选 ): 标识 Hibernate 类 型 的 名 字 © 
© column (可 选 - 默认 为 属性 名 ): 主键 字段 的 名 字 。 


unsaved-value (可 选 - 默认 为 一 个 切合 实际 (sensible) 的 值 ): 一 个 特定 
的 标识 属性 值 ， 用 来 标志 该 实例 是 刚刚 创建 的 ， 尚 未 保存 。 这 可 以 把 这 种 实 
例 和 从 以 前 的 session 中 装载 过 (可 能 又 做 过 修改 -- 译 者 注 ) 但 未 再 次 持久 化 
的 实例 区 分 开 来 。 


© access (可 选 - 软 认 为 property ): Hibernate 用 来 访问 属性 值 的 策略 。 


© 


如 果 name 属性 不 存在 ， 会 认为 这 个 类 没有 标识 属性 。 
unsaved-value 属性 在 Hibernate3 中 几乎 不 再 需要 。 


还 有 一 个 另外 的 &lt;composite-id&gt; 定义 可 以 访问 旧式 的 多 主键 数据 。 我们 
强烈 不 建议 使 用 这 种 方式 。 


5.1.4.1. Generator 


可 选 的 &lt;generator&gt; 子 元 素 是 一 个 Java 类 的 名 字 ， 用 来 为 该 持久 化 类 的 
实例 生成 唯一 的 标识 。 如 果 这 个 生成 器 实例 需要 某 些 配置 值 或 者 初始 化 参数 ， 
用 @lt;param&gt; 元 素来 传递 。 


<id name="id" type="long" column="cat_id"> 
<generator class="org.hibernate.id.TableHiLoGenerator"> 
<param name="table">uid_table</param> 
<param name="column">next_hi_value_column</param 
> 


</generator> 
</id> 


所 有 的 生成 器 都 实现 org. hibernate.id.IdentifierGenerator 接口 。 这 是 一 
个 非常 简单 的 接口 ; 某 些 应 用 程序 可 以 选择 提供 他 们 自己 特定 的 实现 。 当 然 ， 
Hibernate 提 供 了 很 多 内 置 的 实现 。 下 面 是 一 些 内 置 生 成 器 的 快捷 名 字 : 


increment 

FIFA long, short RA int 类 型 生成 唯一 标识 。 只 有 在 没有 其 他 进程 往 同 
一 张 表 中 插入 数据 时 才能 使 用 。 在 集群 下 不 要 使 用 。 

identity 

xt DB2,MySQL, MS SQL Server, Sybase 和 HypersonicSQL 的 内 置 标识 字段 提供 支 
持 。 返回 的 标识 符 是 long, short 或 者 int 类 型 的 。 


sequence 


4£DB2,PostgreSQL, Oracle, SAP DB, McKoi 中 使 用 序列 (sequence)? 而 在 
Interbase 中 使 用 生成 器 (generator)。 返 回 的 标识 符 是 long , short 或 者 

int 类 型 的 。 

hilo 

<a class="calibre5 pcalibre pcalibre1" id="mapping-declaration-id- 
hilodescription"></a> 使 用 一 个 高 /低位 算法 高 效 的 生成 long , short 或 者 

int 类 型 的 标识 符 。 给 定 一 个 表 和 字段 (默认 分 别 是 hibernate _unique_key 
和 next_hi ) 作为 高 位 值 的 来 源 。 高 /低位 算法 生成 的 标识 符 只 在 一 个 特定 的 数据 
库 中 是 唯一 的 。 


seqhilo 


使 用 一 个 高 /低位 算法 来 高 效 的 生成 long, short 或 者 int 类 型 的 标识 符 ， 给 
定 一 个 数据 库 序 列 (sequence) 的 名 字 。 


uuid 


用 一 个 128-bit 的 UUID 算 法 生成 字符 串 类 型 的 标识 符 ， 这 在 一 个 网 络 中 是 唯一 的 
(使 用 了 IP 地 址 ) 。UUID 被 编码 为 一 个 32 位 16 进 制 数 字 的 字符 串 。 


guid 
在 MS SQL Server 和 MySQL 中 使 用 数据 库 生 成 的 GUID 字 符 串 。 

native 

根据 底层 数据 库 的 能 力 选择 identity , sequence 或 者 hilo 中 的 一 个 。 
assigned 

让 应 用 程序 在 save() 之 前 为 对 象 分 配 一 个 标示 符 。 这 是 
&lt;generator&gt; 元素 没有 指定 时 的 默认 生成 策略 。 

select 

过 数据 库 触 发 器 选择 一 些 唯一 主键 的 行 并 返回 主键 值 来 分 配 一 个 主键 。 

foreign 


使 用 另外 一 个 相关 联 的 对 象 的 标识 符 。 通 常 和 &lt;one-to-one&gt; 联合 起 来 使 
用 。 


sequence-identity 


一 种 特别 的 序列 生成 策略 ,使 用 数据 库 序列 来 生成 实际 值 ,但 将 它 和 JDBC3 的 
getGeneratedKeys 结 合 在 一 起 ,使 得 在 插入 语句 执行 的 时 候 就 返回 生成 的 值 。 目 前 
为 止 只 有 面向 JDK 1.4 的 Oracle 10g 驱 动 支持 这 一 策略 。 注 意 ， 因 为 Oracle 驱 动 程序 
的 一 个 bug， 这 些 插入 语句 的 注释 被 关闭 了 。 (原文 : Note comments on these 
insert statements are disabled due to a bug in the Oracle drivers. ) 


5.1.4.2. 高 /低位 算法 (Hi/Lo Algorithm ) 


hilo 和 seqhilo 生成 器 给 出 了 两 种 hi/lo 算 法 的 实现 ， 这 是 一 种 很 令 人 满意 的 
标识 符 生 成 算法 。 第 一 种 实现 需要 一 个 “特殊 ”的 数据 库 表 来 保存 下 一 个 可 用 
的 “hi" 值 。 第 二 种 实现 使 用 一 个 Oracle 风 格 的 序列 (在 被 支持 的 情况 下 ) © 


<id name="id" type="long" column="cat_id"> 
<generator class="hilo"> 
<param name="table">hi_value</param> 
<param name="column">next_value</param> 
<param name="max_lo">100</param> 
</generator> 
</id> 


<id name="id" type="long" column="cat_id"> 
<generator class="seqhilo"> 
<param name="sequence">hi_value</param> 
<param name="max_lo">100</param> 
</generator> 
</id> 


很 不 幸 ， 你 在 为 Hibernate 自 行 提 供 Connection 时 无 法 使 用 hilo ° 3 
Hibernate 使 用 JTA 获 取 应 用 服务 器 的 数据 源 连接 时 ,你 必须 正确 地 配置 
hibernate.transaction.manager_lookup_class ° 


5.1.4.3. UUID 算 法 (UUID Algorithm ) 


UUID EA : IP 地 址 ，JVM 的 启动 时 间 (精确 到 1/4 秒 ) ， 系 统 时 间 和 一 个 计数 器 值 
(在 JVM 中 唯一 ) 。 在 Java 代 码 中 不 可 能 获得 MAC 地 址 或 者 内 存 地 址 ， 所 以 这 已 
经 是 我 们 在 不 使 用 JNI 的 前 提 下 的 能 做 的 最 好 实现 了 。 


5.1.4.4. 标识 字段 和 序列 (Identity columns and 
Sequences ) 


对 于 内 部 支持 标识 字段 的 数据 库 (DB2,MySQL,Sybase,MS SQL)， 你 可 以 使 

用 identity 关键 字 生 成 。 对 于 内 部 支持 序列 的 数据 库 〈DB2,Oracle， 
PostgreSQL, Interbase, McKoi,SAP DB), 你 可 以 使 用 sequence 风格 的 关键 字 生 
成 。 这 两 种 方式 对 于 插入 一 个 新 的 对 象 都 需要 两 次 SQL 查询 。 


<id name="id" type="long" column="person_id"> 
<generator class="sequence"> 
<param name="sSequence">person_id_sequence</param 
> 
</generator> 
</id> 


<id name="id" type="long" column="person_id" unsaved-value="0"> 
<generator class="identity"/> 
</id> 


对 于 跨 平 台 开 发 ， native 策略 会 从 identity , sequence 和 hilo 中 进行 选 
择 ， 选 择 哪 一 个 ， 这 取决 于 底层 数据 库 的 支持 能 力 。 


5.1.4.5. 程序 分 配 的 标识 符 (Assigned 
Identifiers 


如 果 你 需要 应 用 程序 分 配 一 个 标示 符 〈 而 非 Hibernate 来 生成 ) ， 你 可 以 使 

用 assigned 生成 器 。 这 种 特殊 的 生成 器 会 使 用 已 经 分 配给 对 象 的 标识 符 属 性 的 
标识 符 值 。 这 个 生成 器 使 用 一 个 自然 键 (natural key， 有 商业 意义 的 列 一 译注 ) 作 
为 主键 ， 而 不 是 使 用 一 个 代理 键 ( surrogate key， 没 有 商业 意义 的 列 一 译注 ) 。 这 
是 没有 指定 &lt;generator&gt; 元 素 时 的 默认 行为 


当选 择 assigned 生成 器 时 ， 除 非 有 一 个 version 或 timestamp 属 性 ， 或 者 你 定义 了 
Interceptor.isUnsaved() ， 否 则 需要 让 Hiberante 使 用 
unsaved-value="undefined" ， 强 制 Hibernatet 查 询 数 据 库 来 确定 一 个 实例 是 瞬 
时 的 (transient) 还 是 脱 管 的 (detached) 。 


5.1.4.6. 触发 器 实现 的 主键 生成 器 (Primary keys 
assigned by triggers ) 


仅仅 用 于 遗留 的 schema 中 (Hibernate 不 能 使 用 触发 器 生成 DDL)。 


<id name="id" type="long" column="person_id"> 
<generator class="Sselect"> 
<param name="key">socialSecurityNumber</param> 
</generator> 
</id> 


在 上 面 的 例子 中 ， 类 定义 了 一 个 命名 为 socialSecurityNumber 的 唯一 值 属性 ， 
它 是 一 个 自然 键 (natural key) > # 4A person_id 的 代理 键 (surrogate key) 
的 值 由 触发 器 生成 。 


5.1.5. composite-id 


<composite-id 
name="propertyName" 
class="ClassName" 
mapped="true| false" 
access="field|property|ClassName" 
node="element-name|." 
> 


<key-property name="propertyName" type="typename" column 
="column_name"/> 

<key-many-to-one name="propertyName class="ClassName" co 
lumn="column_name"/> 


</composite-id> 


如 果 表 使 用 联合 主键 ， 你 可 以 映射 类 的 多 个 属性 为 标识 符 属 性 。 
&lt;composite-id&gt; AZ &lt;key-propertyagt; 属性 映射 
和 &lt;key-many-to-oneagt; 属性 映射 作为 子 元 素 。 


<composite-id> 
<key-property name="medicareNumber"/> 
<key-property name="dependent"/> 
</composite-id> 


你 的 持久 化 类 必须 重 载 equals() 和 hashCode() 方法 ， 来 实现 组 合 的 标识 符 的 
相等 判断 。 实现 Serializable 接口 也 是 必须 的 。 


不 幸 的 是 ， 这 种 组 合 关键 字 的 方法 意味 着 一 个 持久 化 类 是 它 自己 的 标识 。 除 了 对 象 
自己 之 外 ， 没 有 什么 方便 的 "把手" 可 用 。 你 必须 初始 化 持久 化 类 的 实例 ， 卉 充 它 的 
标识 符 属 性 ， 再 load() 组 合 关键 字 关 联 的 持久 状态 。 我 们 把 这 种 方法 称 为 
embedded (XAR) 的 组 合 标识 符 ， 在 重要 的 应 用 中 不 鼓励 使 用 这 种 用 法 。 


第 二 种 方法 我 们 称 为 mapped( 映 射 式 ) 组 合 标识 符 (mapped composite 
identifier), &1t;composite-idagt; 元 素 中 列 出 的 标识 属性 不 但 在 持久 化 类 出 现 ， 
还 形成 一 个 独立 的 标识 符 类 。 


<composite-id class="MedicareId" mapped="true"> 
<key-property name="medicareNumber"/> 
<key-property name="dependent"/> 
</composite-id> 


在 这 个 例子 中 ， 组 合 标识 符 类 MedicareId 和 实体 类 都 含 

有 medicareNumber 和 dependent 属性 。 标 识 符 类 必须 重 

载 equals() 和 hashCode() 并 且 实 现 Serializable 接口 。 这 种 方法 的 缺点 是 
出 现 了 明显 的 代码 重复 。 


下 面 列 出 的 属性 是 用 来 指定 一 个 映射 式 组 合 标识 符 的 : 


e mapped (可 选 , RUX false ): 指明 使 用 一 个 映射 式 组 合 标识 符 ， 其 包含 的 
属性 映射 同时 在 实体 类 和 组 合 标识 符 类 中 出 现 。 


e class (可 选 ,但 对 映射 式 组 合 标 识 符 必须 指定 ): 作为 组 合 标识 符 类 使 用 的 类 
名 . 


在 第 8.4 节 “ 组 件 作为 联合 标识 符 (Components as composite elle 一 节 中 ,我 
们 会 描述 第 三 种 方式 , 那 就 是 把 组 合 标 识 符 实现 为 一 个 组 件 (component) 类 ,这 是 更 方 


便 的 方法 。 下 面 的 属性 仅 对 第 


e name (可 选 ,但 对 这 种 方法 而 言 必 须 ): 包含 此 组 件 标 识 符 的 组 件 类 型 的 名 字 
(参阅 第 9 章 )， 


e access (可 选 - 默认 为 property ): Hibernate 应 该 使 用 的 访问 此 属性 值 的 策 
略 


e class (可 选 - 默认 会 用 反射 来 自动 判定 属性 类 型 ): 用 来 作为 组 合 标识 符 的 
组 件 类 的 类 名 (参阅 下 一 节 ) 


A 一 


第 三 种 方式 ， 被 称 为 jdentifier component( 标 识 符 组 件 ) 是 我 们 对 几乎 所 有 应 用 都 推 
荐 使 用 的 方式 。 


5.1.6. 鉴别 器 (discriminator) 


在 "一 棵 对 象 继承 树 对 应 一 个 表 " 的 策略 中 ， &lt;discriminator&gt; 元 素 是 必需 
它 定 义 了 表 的 鉴别 器 字段 。 鉴 别 器 字段 包含 标志 值 ， 用 于 告知 持久 化 层 应 该 为 
个 特定 的 行 创 。 如 下 这 些 受 到 限制 的 类 型 可 以 使 用 : 

, character , integer ，byte , short , boolean , yes_no 

true_false . 


<discriminator 
column="discriminator_column" 
type="discriminator_type" 
force="true|false" 
insert="true|false" 
formula="arbitrary sql expression" 


/> 


© column (可 选 - 默认 为 class ) 鉴别 器 字段 的 名 字 

@ type (可 选 -默认 为 string ) 一 个 Hibernate 字 段 类 型 的 名 字 

force( 强 制 ) (可 选 - 默认 为 false ) "强制 "Hibernate 指 定 允 许 的 鉴别 器 

值 ,即使 当 取 得 的 所 有 实例 都 是 根 类 的 。 

insert (可 选 - RUA true as p 果 你 的 鉴别 器 字段 也 是 映射 为 复合 标识 

@ (composite identifier) 的 一 部 分 ， 则 需 将 这 个 值 设 为 false 。 (告诉 
Hibernate 在 做 SQL INSERT 时 不 包含 该 列 ) 


@ formula (可 选 ) 一 个 SQL 表达 式 ， 在 类 型 判断 〈 判 断 是 父 类 还 是 具体 子 类 
一 译注 ) 时 执行 。 可 用 于 基于 内 容 的 鉴别 器 。 


鉴别 器 字段 的 实际 值 是 根据 &lt;class&gt; 和 &lt;subclass&gt; TAP 
的 discriminator-value 属性 得 来 的 。 


force 属 性 仅仅 在 这 种 情况 下 有 用 的 : 表 中 包含 没有 被 映射 到 持久 化 类 的 附加 辩 
别 器 值 。 这 种 情况 不 会 经 常 遇 到 。 
使 用 formula 属性 你 可 以 定义 一 个 SQL 表达 式 ， 用 来 判断 一 个 行 数据 的 类 型 。 


<discriminator 
formula="case when CLASS TYPE in ('a', 'b', 'c') then 0 else 
1 end" 
type="integer"/> 
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5.1.7. 版 本 (version) (可 选 ) 


&lt;versionggt; 元 素 是 可 选 的 ， 表 明 表 中 包含 附带 版 本 信息 的 数据 。 这 在 你 准 
备 使 用 长 事务 (long transactions) 的 时 候 特别 有 用 。 (We) 


<version 
column="version_column" 
name="propertyName" 
type="typename" 
access="field|property|ClassName" 
unsaved -value="null1|negative|undefined" 
generated="never | always" 
insert="true|false" 
node="element -name|@attribute-name|element/@attribute|." 


/> 

© column (可 选 - 默认 为 属性 名 ): 指定 持 有 版 本 号 的 字段 名 。 

@ name :持久 化 类 的 属性 名 。 

© type (可 选 -默认 是 integer ): 版 本 号 的 类 型 。 

© access (可 选 - 默认 是 property ): Hibernate 用 于 访问 属性 值 的 策略 。 


unsaved-value (可 选 - 默认 是 undefined ): 用 于 标明 某 个 实例 时 刚刚 被 
实例 化 的 (尚未 保存 ) 版 本 属性 值 ， 依 靠 这 个 值 就 可 以 把 这 种 情况 和 已 经 在 
先前 的 session 中 保存 或 装载 的 脱 管 (detached) 实例 区 分 开 来 。 

( undefined 指明 应 被 使 用 的 标识 属性 值 。) 


generated (可 选 - 默 认 是 never ): 表明 此 版 本 属性 值 是 否 实 际 上 是 由 数 
O 据 库 生成 的 。 请 参阅 第 5.6 节 “ 数 据 库 生成 属性 (Generated 
Properties) "部 分 的 讨论 。 


ọ insert (可 选 -默认 是 true ) 表明 此 版 本 列 应 该 包含 在 SQL 插 入 语句 
中 。 只 有 当 数 据 库 字段 有 上 默认 值 O 的 时 候 ， a false 。 
版 本 号 必须 是 以 下 类 型 : long, integer, short , timestamp 或 
者 calendar 。 


一 个 脱 管 (detached) 实例 的 version 或 timestamp 属 性 不 能 为 室 (null) > AA 
Hibernate 不 管 unsaved-value 被 指定 为 何 种 策略 ， 它 将 任何 属性 为 空 的 version 
或 timestamp 实例 看 作为 瞬时 (transient) 实例 。 避免 Hibernate 中 的 传递 重 附 
(transitive reattachment) 问题 的 一 个 简单 方法 是 定义 一 个 不 能 为 空 的 version 或 
timestamp 属 性， 特别 是 在 人 们 使 用 程序 分 配 的 标识 符 (assigned identifiers) 或 
复合 主键 时 非常 有 用 ! 
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5.1.8. timestamp (可 选 ) 


可 选 的 &lt;timestampagt; 元 素 指 明了 表 中 包含 时 间 惟 数据 。 这 用 来 作为 版 本 
的 替代 。 时 间 惟 本 质 上 是 一 种 对 乐观 锁定 的 一 种 不 是 特别 安全 的 实现 。 当 然 ， 有 时 
候 应 用 程序 可 能 在 其 他 方面 使 用 时 间 蕉 。 


<timestamp 

column="timestamp_column" 

name="propertyName" 

access="field|property|ClassName" 

unsaved -value="null1|undefined" 

source="vm|db" 

generated="never | always" 

node="element -name|@attribute-name|element/@attribute|." 
/> 


© column (可 选 - 默认 为 属性 名 ): HAN ARN FR o 
@ name : 在 持久 化 类 中 的 JavaBeans 风 格 的 属性 名 ， 其 Java 类 型 是 Date 


或 者 Timestamp 的 。 
© access (可 选 - 默 认 是 property ): Hibernate 用 于 访问 属性 值 的 策略 。 


unsaved-value (可 选 -默认 是 null ): 用 于 标明 某 个 实例 时 刚刚 被 实例 
化 的 (尚未 保存 ) 版 本 属性 值 ， 依 靠 这 个 值 就 可 以 把 这 种 情况 和 已 经 在 先前 
的 session 中 保存 或 装载 的 脱 管 (detached) 实例 区 分 开 来 。 

( undefined 指明 使 用 标识 属性 值 进 行 这 种 判断 。) 


source (可 选 -默认 是 vm ): Hibernate 如何 才能 获取 到 时 间 改 的 值 呢 ? 
从 数据 库 ， 还 是 当前 JVM ? 从 数据 库 获 取 会 带 来 一 些 负担 ， 因 为 Hibernate 必 
= 须 访 问 数据 库 来 获得 “下 一 个 值 ”， 但 是 在 集群 环境 中 会 更 安全 些 。 还 要 注 
意 ， 并 不 是 所 有 的 Dialect (FF) 都 支持 获得 数据 库 的 当前 时 间 稚 的 ， 
而 支持 的 数据 库 中 又 有 一 部 分 因为 精度 不 足 ,用 于 锁定 是 不 安全 的 (例如 
Oracle 8) 。 
generated (可 选 -默认 是 never ): 指出 时 间 惟 值 是 否 实际 上 是 由 数据 库 
@ 生成 的 .请 参阅 第 5.6 节 “ 数 据 库 生 成 属性 (Generated Properties) ”的 讨 


论 。 


注意 ， &lt;timestamp&gt; 和 &lt;version type="timestamp"&gt; Æ ¥ 
的 。 并 

HL &lt;timestamp source="db"&gt; 和 &lt;version type="dbtimestamp"&gt 
是 等 价 的 。 
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5.1.9. property 
&lt;property&gt; 元 素 为 类 定义 了 一 个 持久 化 的 ,JavaBean 风 格 的 属性 。 


<property 
name="propertyName" 
column="column_name" 
type="typename" 
update="true|false" 
insert="true|false" 
formula="arbitrary SQL expression" 
access="field|property|ClassName" 
lazy="true|false" 
unique="true|false" 
not-null="true|false" 
optimistic-lock="true| false" 
generated="never |insert|always" 
node="element -name|@attribute-name|element/@attribute|." 


index="index_name" 
unique_key="unique_key_id" 
length="L" 
precision="P" 
scale="S" 

/> 


name : 属性 的 名 字 , 以 小 写字 母 开 头 。 


column (可 选 - 默认 为 属性 名 字 ): 对 应 的 数据 库 字 段 名 。 也 可 以 通过 髓 套 
的 &lt;column&gt; 元 素 指定 。 


type (可 选 ): 一 个 Hibernate 类 型 的 名 字 。 


update, insert (TŻ -RUX true ) :表明 用 于 UPDATE 和 /或 
INSERT 的 SQL 语 名 中 是 否 包 含 这 个 被 映射 了 的 字段 。 这 二 者 如 果 都 设置 
为 false 则 表明 这 是 一 个 “外 源 性 (derived) ”的 属性 ， 它 的 值 来 源 于 映射 
到 同一 个 (或 多 个 ) 字段 的 茶 些 其 他 属性 ， 或 者 通过 一 个 trigger( 触 发 器 ) 
或 其 他 程序 生成 。 

formula (可 选 ): 一 个 SQL 表达 式 ， 定 义 了 这 个 计算 (computed) 属性 的 
值 。 计 算 属性 没有 和 它 对 应 的 数据 库 字段 。 

access (可 选 - 默认 值 为 property ): Hibernate 用 来 访问 属性 值 的 策 
略 。 

lazy (可 选 -默认 为 false ): 指定 指定 实例 变量 第 一 次 被 访问 时 ， 这 个 
属性 是 否 延迟 抓 取 (fetched lazily) ( 需要 运行 时 字 节 码 增强 ) © 

unique (可 选 ) 使 用 DDL 为 该 字段 添加 唯一 的 约束 。 同样 ， 允 许 它 作 

为 property-ref 引用 的 目标 。 

not-null (TÈ): 使 用 DDL 为 该 字段 添加 可 否 为 室 (nullability) 的 约束 。 
optimistic-lock (可 选 - 默认 为 true ): 指定 这 个 属性 在 做 更 新 时 是 否 
需要 获得 乐观 锁定 (optimistic lock) 。 换 多 话说 ， 它 决定 这 个 属性 发 生 脏 
数据 时 版 本 (version) 的 值 是 否 增长 。 

generated (可 选 - RUA never ): 表明 此 属性 值 是 否 实际 上 是 由 数据 库 
生成 的 。 请 参阅 第 5.6 节 “ 数 据 库 生 成 属性 〈Generated Properties) "的 讨 


论 。 


typename 可 以 是 如 下 几 种 : 


1 


Hibernate 基 本 类 型 名 (re 
如 : integer, string, character,date, timestamp, float, binary, 


) o 


. 一 个 Java 类 的 名 字 ， 这 个 类 属于 一 种 默认 基础 类 型 (比如 : 


S 


int, float,char, java.lang.String, java.util.Date, java.lang.Int 


)e 


. 一 个 可 以 序列 化 的 Java 类 的 名 字 。 
. 一 个 自 定义 类 型 的 类 的 名 字 。 (比如 : 


com.illflow.type.MyCustomType )° 


p 果 你 没有 指定 类 型 ，Hibernarte 会 使 用 反射 来 得 到 这 个 名 字 的 属性 ， 以 此 来 猜测 
正确 的 Hibernate 类 型 。 Hibernate 会 按照 规则 2,3,4 的 顺序 对 属性 读 取 器 (getter 方 
法 ) 的 返回 类 进行 解释 。 然 而 ， 这 还 不 够 。 在 某 些 情况 下 你 仍然 需要 type & 
性 。 (比如 ， 为 了 区 别 Hibernate.DATE 和 Hibernate.TIMESTAMP ,或 者 为 了 指 
RPE EXRA © ) 


access 属性 用 来 让 你 控制 Hibernate 如 何在 运行 时 访问 属性 。 在 默认 情况 下 ， 
Hibernate 会 ee eee a ( pair ) ERRA a access="field" | 
Hibernate 会 ; 忽略 get/set 方 法 对 ， 直 接 使 用 反射 来 访问 成 员 变量 。 你 也 可 以 指定 你 自 
己 的 策略 ， 这 就 需要 你 自己 实 

现 org.hibernate.property.PropertyAccessor 接口 ， 再 在 access 中 设置 你 自 
定义 策略 类 的 名 字 。 


衍生 属性 〈derive propertie) 是 一 个 特别 强大 的 特征 。 这 些 属性 应 该 定义 为 只 读 ， 
属性 值 在 装载 时 计算 生成 。 你 用 一 个 SQL 表达 式 生成 计算 的 结果 ， 它 会 在 这 个 实例 
转载 时 翻译 成 一 个 SQL 查询 的 SELECT FAA A o 


<property name="totalPrice" 
formula="( SELECT SUM (1li.quantity*p.price) FROM LineItem li 
, Product p 
WHERE 1li.productId = p.productId 
AND 1i.customerId = customerId 
AND 1i.orderNumber = orderNumber )"/> 


注意 ， 你 可 以 使 用 实体 自己 的 表 ， 而 不 用 为 这 个 特别 的 列 定义 别名 ( 上 面 例子 中 
的 customerId ) 。 同 时 注意 ， 如 果 你 不 喜欢 使 用 属性 ， 你 可 以 使 用 睹 套 
的 &lt;formula&gt， 映射 元 素 。 


5.1.10. 多 对 一 《many-to-one ) 


通过 many-to-one 元 素 , 可 以 定义 一 种 常见 的 与 另 一 个 持久 化 类 的 关联 。 这 种 关 
系 模型 是 多 对 一 关联 (实际 上 是 一 个 对 象 引 用 一 译注 ) : 这 个 表 的 一 个 外 键 引用 目 
标 表 的 主键 字段 。 


<many-to-one 
name="propertyName" 
column="column_name" 
class="ClassName" 
cascade="cascade_style" 
fetch="join|select" 
update="true|false" 
insert="true|false" 
property-ref="propertyNameFromAssociatedClass" 
access="field|property|ClassName" 
unique="true|false" 
not-null="true|false" 
optimistic-lock="true| false" 
lazy="proxy|no-proxy|false" 
not -found="ignore|exception" 
entity-name="EntityName" 
formula="arbitrary SQL expression" 
node="element -name|@attribute-name|element/@attribute|." 


embed-xml="true|false" 
index="index_name" 
unique_key="unique_key_id" 
foreign-key="foreign_key_name" 


/> 


@ name :属性 名 。 

column (可 选 ): 外 间 字 段 名 。 它 也 可 以 通过 凯 套 的 &lLt;column&gt; 元 
素 指定 。 
© class (可 选 - 默认 是 通过 反射 得 到 属性 类 型 ): 关联 的 类 的 名 字 。 
@ cascade (AK) (Fi): 指明 哪些 操作 会 从 父 对 象 级 联 到 关联 的 对 象 。 
fetch (可 选 - 默认 为 select ): 在 外 连接 抓 取 (outer-join fetching) 和 
序列 选择 抓 取 (sequential select fetching) 两 者 中 选择 其 一 。 

update, insert (可 选 -默认 为 true ) 指定 对 应 的 字段 是 否 包含 在 用 
于 UPDATE 和 /或 INSERT 的 SQL 语句 中 。 如 果 二 者 都 是 false MRE 
@ 一 个 纯粹 的 “外 源 性 〈derived) "关联 ， 它 的 值 是 通过 映射 到 同一 个 (或 多 
个 ) 字段 的 某 些 其 他 属性 得 到 或 者 通过 trigger( 触 发 器 ) 、 或 其 他 程序 生 
成 o 

property-ref : (可 选 ) 指定 关联 类 的 一 个 属性 ， 这 个 属性 将 会 和 本 外 键 相 
对 应 。 如 果 没 有 指定 ， 会 使 用 对 方 关联 类 的 主键 。 
@ access (可 选 - 默认 是 property ): Hibernate 用 来 访问 属性 的 策略 。 
unique (可 选 ): 使 用 DDL 为 外 键 字 段 生 成 一 个 唯一 约束 。 此 外 ， 这 也 可 以 
用 作 property-ref 的 目标 属性 。 这 使 关联 同时 具有 一 对 一 的 效果 。 


© not-null (可 选 ): 使 用 DDL 为 外 键 字 段 生 成 一 个 非 空 约 束 。 


optimistic-lock (可 选 -默认 为 true ) 指定 这 个 属性 在 做 更 新 时 是 否 
@ 需要 获得 乐观 锁定 (optimistic lock) 。 换 句 话说 ， 它 决定 这 个 属性 发 生 脏 
数据 时 版 本 (version) 的 值 是 否 增长 。 


lazy (可 选 - 默认 为 ”proxy ): 默认 情况 下 ， 单 点 关联 是 经 过 代理 

的 。 lazy="no-proxy" 指定 此 属性 应 该 在 实例 变量 第 一 次 被 访问 时 应 该 延 
RP (fetche lazily) (需要 运行 时 字 节 码 的 增强 ) © lazy="false" 指 
定 此 关联 总 是 被 预先 抓 取 。 

not-found (可 选 - 默认 为 exception ): 指定 外 键 引用 的 数据 不 存在 时 
如 何 处 理 : ignore 会 将 行 数据 不 存在 视 为 一 个 空 (null) 关联 。 

© ” entity-name (可 选 ): 被 关联 的 类 的 实体 名 。 


© formula (可 选 ): SQL 表 达 式 ， 用 于 定义 computed (计算 出 的 ) 外 键 值 。 


cascade 属性 设置 为 除了 none 以 外 任何 有 意义 的 值 ， 它 将 把 特定 的 操作 传递 到 
关联 对 象 中 。 这 个 值 就 代表 着 Hibernate 基 本 操作 的 名 称 ， 

persist, merge, delete, save-update, evict, replicate, lock, refresl 
> 以 及 特别 的 值 delete-orphan 和 all ， 并 且 可 以 用 去 号 分 隔 符 来 组 合 这 些 操 
作 ， 例 如 ， cascade="persist,merge,evict" 或 
cascade="all,delete-orphan" 。 更 全 面 的 解释 请 参考 第 10.11 节 “ 传 播 性 持久 
化 (transitive persistence)”. 注意 ， 单 值 关 联 (many-to-one 和 one-to-one 关联 ) 不 
支持 删除 孤儿 (orphan delete， 删 除 不 再 被 引用 的 值 ) . 


一 个 典型 的 简单 many-to-one 定义 例子 : 


<many-to-one name="product" class="Product" column="PRODUCT_ID"/ 
> 


property-ref 属性 只 应 该 用 来 对 付 遗 留 下 来 的 数据 库 系统 ， 可 能 有 外 键 指向 对 
方 关联 表 的 是 个 非 主 键 字 段 (但 是 应 该 是 一 个 惟一 关键 字 ) 的 情况 下 。 这 是 一 种 十 
分 斑 陋 的 关系 模型 。 比 如 说 ， 假 设 Product 类 有 一 个 + Een 列 号 ， 它 并 不 是 主 
键 。( unique 属性 控制 Hibernate 通 过 SchemaExport 工 具 进行 的 DDL 生 成 。) 


<property name="serialNumber" unique="true" type="string" column 
="SERIAL_NUMBER"/> 


那么 关于 OrderItem 的 映射 可 能 是 


<many-to-one name="product" property-ref="SerialNumber" column=" 
PRODUCT_SERIAL_NUMBER"/> 


当然 ， 我 们 决 不 鼓励 这 种 用 法 。 


如 果 被 引用 的 唯一 主键 由 关联 实体 的 多 个 属性 组 成 ， 你 应 该 在 名 称 
A &lt;properties&gt; 的 元 素 里 面 映射 所 有 关联 的 属性 。 


假若 被 引用 的 唯一 主键 是 组 件 的 属性 ， 你 可 以 指定 属性 路 径 : 


<many-to-one name="owner" property-ref="identity.ssn" column="0W 
NER_SSN"/> 


5.1.11. 一 对 一 
持久 化 对 象 之 间 一 对 一 的 关联 关系 是 通过 one-to-one 元 素 定义 的 。 


<one-to-one 
name="propertyName" 
class="ClassName" 
cascade="cascade_style" 
constrained="true|false" 
fetch="join|select" 
property-ref="propertyNameFromAssociatedClass" 
access="field|property|ClassName" 
formula="any SQL expression" 
lazy="proxy|no-proxy|false" 
entity-name="EntityName" 
node="element -name|@attribute-name|element/@attribute|." 


embed-xml="true|false" 
foreign-key="foreign_key_name" 
/> 


@ name : 属性 的 名 字 。 

@ class (可 选 - 默认 是 通过 反射 得 到 的 属性 类 型 ) : 被 关联 的 类 的 名 字 。 

© cascade( 级 联 ) (可 选 ) 表明 操作 是 否 从 父 对 象 级 联 到 被 关联 的 对 象 。 
constrained(4R) (可 选 ) 表明 该 类 对 应 的 表 对 应 的 数据 库 表 ， 和 被 关联 

m 的 对 象 所 对 应 的 数据 库 表 之 间 ， 通 过 一 个 外 键 引 用 对 主键 进行 约束 。 这 个 选 
项 影响 save() 和 delete() 在 级 联 执行 时 的 先后 顺序 以 及 决定 该 关联 能 
否 被 委托 (也 在 Schema export tool 中 被 使 用 ). 

= fetch (可 选 - 默认 设置 为 选择 ) 在 外 连接 抓 取 或 者 序列 选择 抓 取 选择 其 

@ Property-ref : (可 选 ) 指定 关联 类 的 属性 名 ， 这 个 属性 将 会 和 本 类 的 主键 
相对 应 。 如 果 没 有 指定 ， 会 使 用 对 方 关 联 类 的 主键 。 

@ access (可 选 - 默 认 是 property ): Hibernate 用 来 访问 属性 的 策略 。 
formula (可 选 ): 绝 大 多 数 一 对 一 的 关联 都 指向 其 实体 的 主键 。 在 一 些 少 见 

的 情况 中 ， 你 可 能 会 指向 其 他 的 一 个 或 多 个 字段 ， 或 者 是 一 个 表达 式 ， 这 些 
情况 下 ， 你 可 以 用 一 个 SQL 公式 来 表示 。 (可 以 在 
org.hibernate.test.onetooneformula 找 到 例子 ) 
lazy (可 选 - 默认 为 proxy ): 默认 情况 下 ， 单 点 关联 是 经 过 代理 
的 。 lazy="no-proxy" 指定 此 属性 应 该 在 实例 变量 第 一 次 被 访问 时 应 该 延 

© wR (fetche lazily) (需要 运行 时 字 节 码 的 增强 ) 。 lazy="false" 指 
定 此 关联 总 是 被 预先 抓 取 。 注 意 ， 如 果 constrained="false" ,不 可 能 使 
用 代理 ，Hibernate 会 采取 预先 抓 取 ! 

© entity-name (可 选 ): 被 关联 的 类 的 实体 名 。 

有 两 种 不 同 的 一 对 一 关联 : 
© 主键 关联 
o 惟一 外 键 关联 


主键 关联 不 需要 额外 的 表 字 段 ; 如 果 两 行 是 通过 这 种 一 对 一 关系 相关 联 的 ， 那 么 这 
希望 两 


两 行 就 共享 同样 的 主 关键 字 值 。 所 以 如 果 你 


过 
望 两 个 对 象 通过 主键 一 对 一 关联 ， 你 


必须 确认 它们 被 赋予 同样 的 标识 值 ! 
比如 说 ， 对 下 面 的 Employee 和 Person 进行 主键 一 对 一 关联 : 


<one-to-one name="person" class="Person"/> 


<one-to-one name="employee" class="Employee" constrained="true"/ 


> 


现在 我 们 必须 确保 PERSON 和 EMPLOYEE 中 相关 的 字段 是 相等 的 。 我 们 使 用 一 个 
被 成 为 foreign 的 特殊 的 hibernate 标 识 符 生成 策略 : 


<class name="person" table="PERSON"> 
<id name="id" column="PERSON_ID"> 
<generator class="foreign"> 
<param name="property">employee</param> 
</generator> 
</id> 


<one-to-one name="employee" 
class="Employee" 
constrained="true"/> 
</class> 


一 个 刚刚 保存 的 Person 实例 被 赋予 和 该 Person 的 employee 属性 所 指向 
的 Employee 实例 同样 的 关键 字 值 。 


另 一 种 方式 是 一 个 外 键 和 一 个 惟一 关键 字 对 应 ， 上 面 的 Employee 和 Person 的 
例子 ， 如 果 使 用 这 种 关联 方式 ， 可 以 表达 成 : 


<many-to-one name="person" class="Person" column="PERSON_ID" uni 
que="true"/> 


如 果 在 Person 的 映射 加 入 下 面 几 句 ， 这 种 关联 就 是 双向 的 : 


<one-to-one name"employee" class="Employee" property-ref="person 
WS 


5.1.12. 自然 ID(natural-id) 


<natural-id mutable="true|false"/> 
<property ... /> 
<many-to-one ... /> 


</natural-id> 


我 们 建议 使 用 代用 键 〈 键 值 不 具备 实际 意义 ) 作为 主键 ， 我 们 仍然 应 该 尝试 为 所 有 
的 实体 采用 自然 的 键 值 作为 (附加 一 一 译 者 注 ) 标示 。 自 然 键 (natural key) 是 单 
个 或 组 合 属 性 ， 他 们 必须 唯一 且 非 定 。 如 果 它 还 是 不 可 变 的 那 就 更 理想 了 。 

在 &lt;natural-id&gt; 元素 中 列 出 自然 键 的 属性 。Hibernate 会 帮 你 生成 必须 的 
唯一 键 值 和 非 空 约束 ， 你 的 映射 会 更 加 的 明显 易 懂 (原文 是 self-documenting， 自 
我 注解 ) 。 

我 们 强烈 建议 你 实现 equals() 和 hashCode() 方法 ,来 比较 实体 的 自然 键 属性 。 
这 一 映射 不 是 为 了 把 自然 键 作为 主键 而 准备 的 。 


e mutable (可 选 , RUA false ): 默认 情况 下 ， 自 然 标识 属性 被 假定 为 不 可 
变 的 (常量) ° 





5.1.13. 组 件 (component), 动态 组 件 (dynamic- 


component) 


&1t;componenté&gt; 


元 素 把 子 对 象 的 一 些 元 素 与 父 类 对 应 的 表 的 一 些 字 段 映 射 起 


来 。 然后 组 件 可 以 定义 它们 自己 的 属性 、 组 件 或 者 集合 。 参见 后 面 


的 “Components” 一 章 。 


<component 


name="propertyName" 
class="className" 


insert="t 
update="t 


rue|false" 
rue|false" 


access="field|property|ClassName" 
lazy="true|false" 
optimistic-lock="true| false" 
unique="true|false" 
node="element-name|." 


<property 


<many -to- 


</component> 


name : 属性 名 


© © © © © 


access (可 选 - 


one ee 


class (可 选 - 默认 为 通过 反射 得 到 的 属性 类 型 :组 件 ( 子 ) 类 的 名 字 。 
insert : 被 映射 的 字段 是 否 出 现在 SQL 的 INSERT 语句 中 ? 

update : 被 映射 的 字段 是 否 出 现在 SQL 的 UPDATE 语句 中 ? 

默认 是 property ): Hibernate 用 来 访问 属性 的 策略 。 


Je 


lazy (可 选 -默认 是 false ) 表明 此 组 件 应 在 实例 变量 第 一 次 被 访问 的 
时 候 延 迟 加 载 (需要 编译 时 字 节 码 装 置 器 ) 

optimistic-lock (可 选 - 默认 是 true ): 表 明 更 新 此 组 件 是 否 需要 获取 
乐观 锁 S 换 和 名 话说 ? ee 这 个 属 性 变 RAE EY > 是 否 增 加 版 本 号 (Version) 


unique (可 选 - 
约束 


© 


其 @lt;property&gt; 


&1t;componenté&gt ; 
部 就 可 以 有 一 个 指向 其 


默认 是 false ): 表 明 组 件 映射 的 所 有 字段 上 都 有 唯一 性 


子 标签 为 子 类 的 一 些 属性 与 表 字段 之 间 建 立 映射 。 


元 素 允 许 加 入 一 个 &lt;parent&gt， 子 元 素 ， 在 组 件 类 内 
其 容器 的 实体 的 反 向 引用 。 


&lt;dynamic-component&gt; 元素 允许 把 一 个 Map 映射 为 组 件 ， 其 属性 名 对 应 
map 的 键 值 。 参 见 第 8.5 节 “ 动 态 组 件 (Dynamic components) ”. 


5.1.14. properties 


&lt;properties&gt; 元 素 允 许 定义 一 个 命名 的 逻辑 分 组 (grouping) 包 含 一 个 类 
中 的 多 个 属性 。 这 个 元 素 最 重要 的 用 处 是 允许 多 个 属性 的 组 合作 
为 property-ref 的 目标 (target)。 这 也 是 定义 多 字段 唯一 约束 的 一 种 方便 途径 。 


<properties 
name="logicalName" 
insert="true|false" 
update="true|false" 
optimistic-lock="true|false" 
unique="true|false" 


> 
<property ..... /> 
<many-to-one .... /> 
</properties> 
O name :分 组 的 逻辑 名 称 - 不 是 实际 属性 的 名 称 . 
@ insert :被 映射 的 字段 是 否 出 现在 SQL 的 ”INSERT 语句 中 ? 
© update : 被 映射 的 字段 是 否 出 现在 SQL 的 UPDATE 语句 中 ? 
optimistic-lock (可 选 - 默认 是 true en n ieee 需要 获取 
乐观 锁 。 换 名 话说 ， 当 这 个 属性 变 脏 时 ， 是 否 增 加 版 本 号 (Version) 
@ unique (可 选 - 默认 是 false ): 表 明 组 件 映射 的 所 有 字段 上 都 有 唯一 性 


约束 


例如 ， 如 果 我 们 有 如 下 的 &lt;properties&gt; BRAT: 


<class name="Person"> 
<id name="personNumber"/> 


<properties name="name" 
unique="true" update="false"> 
<property name="firstName"/> 
<property name="initial"/> 
<property name="lastName"/> 
</properties> 
</class> 


然后 ， 我 们 可 能 有 一 留 的 数据 关联 ， 引 用 Person 表 的 这 个 唯一 键 ， 而 不 是 
主键 。 


<many-to-one name="person" 
class="Person" property-ref="name"> 
<column name="firstName"/> 
<column name="initial"/> 
<column name="lastName"/> 
</many - to-one> 


我 们 并 不 推荐 这 样 使 有 用， 除非 在 映射 遗留 数据 的 情况 下 。 


5.1.15. + Žž (subclass) 


最 后 ， 多 态 持 久 化 需要 为 父 类 的 每 个 子 类 都 进行 定义 。 对 于 “每 一 棵 类 继承 树 对 应 一 
个 表 ” 的 策略 来 说 ， 就 需要 使 用 &Lt;subclass&gt; 定义 。 


<subclass 
name="ClassName" 
discriminator -value="discriminator_value" 
proxy="ProxyInterface" 
lazy="true|false" 
dynamic -update="true|false" 
dynamic -insert="true|false" 
entity-name="EntityName" 
node="element -name" 
extends="SuperclassName"> 


<property .... /> 


</subclass> 


。 name : 子 类 的 全 限定 名 。 


discriminator-value( 辩 别 标志 ) (可 选 - 默认 为 类 名 ): 一 个 用 于 区 分 每 个 
独立 的 子 类 的 值 加 


。 ”proxy( 代 理 ) (TŻ) 指定 一 个 类 或 者 接口 ， 在 延迟 装载 时 作为 代理 使 用 。 
。 lazy (可 选 , 默认 是 true ): 设置 为 lazy="false" 禁止 使 用 延迟 抓 取 
每 个 子 类 都 应 该 定义 它 自己 的 持久 化 属性 和 子 类 。 &1t;version&gt; 
和 &lt;id&gt; 属性 可 以 从 根 父 类 继承 下 来 。 在 一 棵 继承 树 上 的 每 个 子 类 都 必须 


定义 一 个 唯一 的 discriminator-value 。 如 果 没 有 指定 ， 就 会 使 用 Java 类 的 全 限 
定名 。 


更 多 关于 继承 映射 的 信息 , 参考 第 9 章 继承 映射 (Inheritance Mappings) 章 节 . 


5.1.16. 连接 的 子 类 (joined-subclass) 


此 外 ， 每 个 子 类 可 能 被 映射 到 他 自己 的 表 中 (每 个 子 类 一 个 表 的 策略 )。 被 继承 的 状 
态 通过 和 超 类 的 表 关 联 得 到 。 我 们 使 用 &lt;joined-subclass&gt; 元 素 。 


<joined-subclass 
name="ClassName" 
table="tablename" 
proxy="ProxyInter face" 
lazy="true|false" 
dynamic -update="true|false" 
dynamic -insert="true|false" 
schema="schema" 
catalog="catalog" 
extends="SuperclassName" 
persister="ClassName" 
subselect="SQL expression" 
entity-name="EntityName" 
node="element -name"> 


<key .... > 
<property .... /> 


</joined-subclass> 


o name : 子 类 的 全 限定 名 。 
@ table : 子 类 的 表 名 . 
© proxy (可 选 ): 指定 一 个 类 或 者 接口 ， 在 延迟 装载 时 作为 代理 使 用 。 


s | 项 是 ( 可 选 默认 是 true ): 设置 为 lazy="false" 休止 使 用 延迟 装 
载 。 

这 种 映射 策略 不 需要 指定 辨别 标志 (discriminator) 字 段 。 但 是 ， 每 一 个 子 类 都 必须 使 

用 &1t;key&gt; 元 素 指定 一 个 表 字 段 来 持 有 对 象 的 标识 符 。 本 章 开 始 的 映射 可 以 

被 用 如 下 方式 重 写 : 


<?xml version="1.0"?> 
<!DOCTYPE hibernate-mapping PUBLIC 
"-//Hibernate/Hibernate Mapping DTD//EN" 
"http://hibernate.sourceforge.net/hibernate-mapping-3.0. 
dtd"> 


<hibernate-mapping package="eg"> 


<class name="Cat" table="CATS"> 

<id name="id" column="uid" type="long"> 
<generator class="hilo"/> 

</id> 

<property name="birthdate" type="date"/> 

<property name="color" not-null="true"/> 

<property name="sex" not-null="true"/> 

<property name="weight"/> 

<many-to-one name="mate"/> 

<set name="kittens"> 
<key column="MOTHER"/> 
<one-to-many class="Cat"/> 


</set> 
<joined-subclass name="DomesticCat" table="DOMES 
TIC_CATS"> 
<key column="CAT"/> 
<property name="name" type="string"/> 
</joined-subclass> 
</class> 


<class name="eg.Dog"> 
<!-- mapping for Dog could go here --> 
</class> 


</hibernate-mapping> 


更 多 关于 继承 映射 的 信息 ， 参 考 第 9 章 继承 映射 (Inheritance Mappings) ° 


5.1.17. 联合 子 类 (union-subclass) 


第 三 种 选择 是 仅仅 映射 类 继承 树 中 具体 类 部 分 到 表 中 (每 个 具体 类 一 张 表 的 策略 ) 。 
其 中 ， 每 张 表 定义 了 类 的 所 有 持久 化 状态 ， 包 括 继承 的 状态 。 在 Hibernate 中 ， 并 
不 需要 完全 显 式 地 映射 这 样 的 继承 树 。 你 可 以 简单 地 使 用 单独 

的 &lt;class&gt; 定义 映射 每 个 类 。 然 而 ， 如 果 你 想 使 用 多 态 关 联 ( 例 如 ， 一 个 对 
类 继承 树 中 超 类 的 关联 )， 你 需要 使 用 &1t;union-subclass&gt; 映射 。 


<union-subclass 
name="ClassName" 
table="tablename" 
proxy="ProxyInter face" 
lazy="true|false" 
dynamic -update="true|false" 
dynamic -insert="true|false" 
schema="schema" 
catalog="catalog" 
extends="SuperclassName" 
abstract="true|false" 
persister="ClassName" 
subselect="SQL expression" 
entity-name="EntityName" 
node="element -name"> 


<property .... /> 


</union-subclass> 


0 name : 子 类 的 全 限定 名 。 
@ table : 子 类 的 表 名 
© proxy (可 选 ): 指定 一 个 类 或 者 接口 ， 在 延迟 装载 时 作为 代理 使 用 。 


lazy (可 选 , 默认 是 true): 设置 为 lazy="false" 禁止 使 用 延迟 装 
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这 种 映射 策略 不 需要 指定 辨别 标志 (discriminator) 字 段 。 
更 多 关于 继承 映射 的 信息 ， 参 考 第 9 章 继承 映射 (Inheritance Mappings) ° 


5.1.18. 连接 (join) 


使 用 &lt;join&gt; 元 素 ， 假 若 在 表 之 间 存 在 一 对 一 关联 ,可 以 将 一 个 类 的 属性 映 
射 到 多 张 表 中 。 


<join 
table="tablename" 
schema="owner" 
catalog="catalog" 
fetch="join|select" 
inverse="true|false" 
optional="true|false"> 


<key ... /> 
<property ... /> 


</join> 


@ table : 被 连接 表 的 名 称 。 


schema (可 选 ): 履 盖 由 根 &lt;hibernate-mapping&gt; 元 素 指定 的 模式 
名 称 。 


catalog (可 选 ): 履 盖 由 根 &lt;hibernate-mapping&gt; 元 素 指 定 的 目 
录 名 称 。 


fetch (可 选 -默认 是 join ): 如 果 设 置 为 默认 值 join > Hibernate 将 
使 用 一 个 内 连接 来 得 到 这 个 类 或 其 超 类 定义 的 &Lt; join&gt; ， 而 使 用 一 
个 外 连接 来 得 到 其 子 类 定义 的 &lt;join&gt; 。 如 果 设 置 为 select > M 
Hibernate 将 为 子 类 定义 的 &lt;joinagt; 使 用 顺序 选择 。 这 仅 在 一 行 数 
据 表 示 一 个 子 类 的 对 象 的 时 候 才 会 发 生 。 对 这 个 类 和 其 超 类 定义 

的 &lt;join&gt; ， 依 然 会 使 用 内 连接 得 到 。 


inverse (可 选 -默认 是 false ): 如 果 打 开 ，Hibernate 不 会 插入 或 者 更 
新 此 连接 定义 的 属性 。 

optional (可 选 - 默认 是 false ): 如 果 打 开 ，Hibernate 只 会 会 在 此 连接 定 
义 的 属性 非 空 时 插入 一 行 数据 ， 并 且 总 是 使 用 一 个 外 连接 来 得 到 这 些 属 性 。 


© 


例如 ， 一 个 人 (person) 的 地 址 (address) 信 息 可 以 被 映射 到 单独 的 表 中 (并 保留 所 有 属 
性 的 值 类 型 语义 ) : 


<class name="Person" 
table="PERSON"> 


<id name="id" column="PERSON_ID">...</id> 


<join table="ADDRESS"> 
<key column="ADDRESS_ID"/> 
<property name="address"/> 
<property name="zip"/> 
<property name="country"/> 
</join> 


此 特性 常常 对 遗留 数据 模型 有 用 ， 我 们 推荐 表 个 数 比 类 个 数 少 ， 以 及 细 粒 度 的 领域 
模型 。 然 而 ， 在 单独 的 继承 树 上 切换 继承 映射 策略 是 有 用 的 ， 后 面 会 解释 这 点 。 


5.1.19. 键 (key) 


我 们 目前 已 经 见 到 过 &1lt;key&gt; 元 素 多 次 了 。 这 个 元 素 在 父 映射 元 素 定 义 了 对 
新 表 的 连接 ， 并 且 在 被 连接 表 中 定义 了 一 个 外 键 引 用 原 表 的 主键 的 情况 下 经 常 使 
用 o 


<key 
column="columnname" 
on-delete="noaction|cascade" 
property-ref="propertyName" 
not-null="true|false" 
update="true| false" 
unique="true|false" 

/> 


column (可 选 ): 4 FR ZK o WY VIM TRAY 
&lt;columnagt; 指定 。 


on-delete (可 选 , 默认 是 noaction ): 表明 外 键 关 联 是 否 打 开 数 据 库 级 
别 的 级 联 删 除 。 


property-ref (可 选 ): 表明 外 键 引 用 的 字段 不 是 原 表 的 主键 (提供 给 遗留 
数据 ) 。 


not-null (可 选 ) 表明 外 键 的 字段 不 可 为 空 (这 意味 着 无 论 何 时 外 键 都 是 
主键 的 一 部 分 ) 。 


update (可 选 ): 表明 外 键 决 不 应 该 被 更 新 (这 意味 着 无 论 何 时 外 键 都 是 主 
键 的 一 部 分 ) 。 


unique (可 选 ) 表明 外 键 应 有 唯一 性 约束 (这 意味 着 无 论 何 时 外 键 都 是 主 
键 的 一 部 分 ) 。 


对 那些 看 重 删除 性 能 的 系统 ， 我 们 推荐 所 有 的 键 都 应 该 定义 

A on-delete="cascade" ， 这 样 Hibernate 将 使 用 数据 库 级 

的 ON CASCADE DELETE 约束 ， 而 不 是 多 个 DELETE Wo 注意 ， 这 个 特性 会 绕 
过 Hibernate 通常 对 版 本 数据 (versioned data) 采 用 的 乐观 锁 策 略 。 


not-null 和 update 属性 在 映射 单 向 一 对 多 关联 的 时 候 有 用 。 如 果 你 映射 一 
个 单 向 一 对 多 关联 到 非 空 的 (non-nullable) 外 键 ， 你 必须 
用 @lt;key not-null="true"agt; 定义 此 键 字段 。 


5.1.20. 字段 和 规则 元 素 (column and formula 
elements ) 


任何 接受 column 属性 的 映射 元 素 都 可 以 选择 接受 &lt;columagt; TAX ° A 
样 的 ，formula 子 元 素 也 可 以 替换 &lt;formula&gt; 属性 。 


<column 
name="column_name" 
length="N" 
precision="N" 
scale="N" 


not-null="true|false" 
unique="true|false" 
unique-key="multicolumn_unique_key_name" 
index="index_name" 
sql-type="sql_type_name" 

check="SQL expression" 

default="SQL expression"/> 


<formula>SQL expression</formula> 


column 和 formula 属性 其 至 可 以 在 同一 个 属性 或 关联 映射 中 被 合并 来 表达 ， 
例如 ， 一 些 奇 异 的 连接 条 件 。 


<many-to-one name="homeAddress" class="Address" 
insert="false" update="false"> 
<column name="person_id" not-null="true" length="10"/> 
<formula>'MAILING'</formula> 
</many - to-one> 


5.1.21. 引用 (import) 


假设 你 的 应 用 程序 有 两 个 同样 名 字 的 持久 化 类 ， 但 是 你 不 想 在 Hibernate 查 询 中 使 用 
他 们 的 全 限定 名 。 除 了 依赖 auto-import="true" 以 外 ， 类 也 可 以 被 显 式 
地 “import( 引 用 )》》。 你 其 至 可 以 引用 没有 被 明确 映射 的 类 和 接口 。 


<import class="java.lang.Object" rename="Universe"/> 


<import 
class="ClassName" 
rename="ShortName" 
/> 


0 class : 任何 Java 类 的 全 限定 名 。 
@ rename (TË - 默认 为 类 的 全 限定 名 ): AEW g PT AEA AF o 


5.1.22. any 


这 是 属性 映射 的 又 一 种 类 型 。 &lLt;any&gt; 映射 元 素 定 义 了 一 种 从 多 个 表 到 类 的 
多 态 关联 。 这 种 类 型 的 映射 常常 需要 多 于 一 个 字段 。 第 一 个 字段 持 有 被 关联 实体 的 
类 型 ， 其 他 的 字段 持 有 标识 符 。 对 这 种 类 型 的 关联 来 说 ， 不 可 能 指定 一 个 外 键 约 
束 ， 所 以 这 当然 不 是 映射 (多 态 ) 关 联 的 通常 的 方式 。 你 只 应 该 在 非常 特殊 的 情况 下 
使 用 它 (比如 ， 审 计 |log， 用 户 会 话 数据 等 等 )。 


meta-type 属性 使 得 应 用 程序 能 指定 一 个 将 数据 库 字段 的 值 映 射 到 持久 化 类 的 自 
定义 类 型 。 这 个 持久 化 类 包含 有 用 id-type 指定 的 标识 符 属 性 。 你 必须 指定 从 
meta-type 的 值 到 类 名 的 映射 。 


<any name="being" id-type="long" meta-type="string"> 
<meta-value value="TBL_ANIMAL" class="Animal"/> 
<meta-value value="TBL_HUMAN" class="Human"/> 
<meta-value value="TBL_ALIEN" class="Alien"/> 
<column name="table_name"/> 
<column name="id"/> 

</any> 


<any 
name="propertyName" 
id-type="idtypename" 
meta-type="metatypename" 
cascade="cascade_style" 
access="field|property|ClassName" 
optimistic-lock="true|false" 


<meta-value ... /> 
<meta-value ... /> 
<column .... /> 
<column .... /> 


name : 属性 名 
id-type :标识 符 类 型 


meta-type (可 选 -默认 是 string ): 允许 辨别 标志 (discriminator) 映 射 的 
任何 类 型 


cascade (可 选 -默认 是 none ): 级 联 的 类 型 
access (可 选 -默认 是 property ): Hibernate 用 来 访问 属性 值 的 策略 。 


optimistic-lock (可 选 -默认 是 true) 表明 更 新 此 组 件 是 否 需要 获取 
乐观 锁 。 换 名 话说 ， 当 这 个 属性 变 脏 时 ， 是 否 增 加 版 本 号 (Version) 


5.2. Hibernate 的 类 型 


5.2.1. 实体 (Entities) 和 值 (values) 


为 了 理解 很 多 与 持久 化 服务 相关 的 Java 语 言 级 对 象 的 行为 ， 我 们 需要 把 它们 分 为 两 
类 : 


实体 entity 独立 于 任何 持 有 实体 引用 的 对 象 。 与 通常 的 Java 模 型 相 比 ， 不 再 被 引用 
的 对 象 会 被 当 作 垃圾 收集 掉 。 实 体 必 须 被 显 式 的 保存 和 删除 (除非 保存 和 删除 是 从 父 
实体 向 子 实体 引发 的 级 联 )。 这 和 ODMG 模 型 中 关于 对 象 通过 可 触及 保持 持久 性 有 
一 些 不 同 比较 起 来 更 加 接近 应 用 程序 对 象 通常 在 一 个 大 系统 中 的 使 用 方法 。 实 
体 支 持 循 环 引 用 和 交叉 引用 ， 它 们 也 可 以 加 上 版 本 信息 。 


一 个 实体 的 持久 状态 包含 指向 其 他 实体 和 值 类 型 实例 的 引用 。 值 可 以 是 原始 类 型 ， 
集合 (不 是 集合 中 的 对 象 )， 组 件 或 者 特定 的 不 可 变 对 象 。 与 实体 不 同 ， 值 (特别 是 集 
合 和 组 件 ) 是 通过 可 触及 性 来 进行 持久 化 和 删除 的 。 因 为 值 对 象 (和 原始 类 型 数据 ) 是 
随 着 包含 他 们 的 实体 而 被 持久 化 和 删除 的 ， 他 们 不 能 被 独立 的 加 上 版 本 信息 。 值 没 
有 独立 的 标识 ， 所 以 他 们 不 能 被 两 个 实体 或 者 集合 共享 。 


直到 现在 ， 我 们 都 一 直 使 用 术语 “持久 类 "(persistent class) 来 代表 实体 。 我 们 仍然 会 
这 么 做 。 然而 严格 说 来 ， 不 是 所 有 的 用 户 自 定 义 的 ， 带 有 持久 化 状态 的 类 都 是 实 
体 。 组 件 就 是 用 户 自 定义 类 ， 却 是 值 语 义 的 。 java.lang.String 类 型 的 java 属 
性 也 是 值 语义 的 。 给 了 这 个 定义 以 后 ， 我 们 可 以 说 所 有 JDK 提 供 的 类 型 ( 关 ) 都 是 值 
类 型 的 语义 ， 而 用 于 自 定 义 类 型 可 能 被 映射 为 实体 类 型 或 值 类 型 语义 。 采 用 哪 种 类 
型 的 语义 取决 于 开发 人 员 。 在 领域 模型 中 ， 寻 找 实体 类 的 一 个 好 线索 是 共享 引用 指 
向 这 个 类 的 单一 实例 ， 而 组 合 或 聚合 通常 被 转化 为 值 类 型 。 


我 们 会 在 本 文档 中 重复 碰 到 这 两 个 概念 。 


挑战 在 于 将 java 类 型 系统 (和 开发 者 定义 的 实体 和 值 类 型 ) 映 射 到 SQL/ 数 据 库 类 型 系 
统 。Hibernate 提 供 了 连接 两 个 系统 之 间 的 桥梁 : 对 于 实体 类 型 ， 我 们 使 

用 &lt;class&gt; , &lt;subclass&gt; 等 等 。 对 于 值 类 型 ， 我 们 使 用 
&lt;property&gt; , &lt;component&gt; 及 其 他 ， 通 常 跟随 着 type AHE ° 
这 个 属性 的 值 是 Hibernate 的 映射 类 型 的 名 字 。Hibernate 提 供 了 许多 现成 的 映射 ( 标 
准 的 JDK 值 类 型 )。 你 也 可 以 编写 自己 的 映射 类 型 并 实现 自 定义 的 变换 策略 ， 随 后 我 

们 会 看 到 这 点 。 


所 有 的 Hibernate 内 建 类 型 ， 除 了 collections 以 外 ， 都 支持 空 (null) 语 义 。 





5.2.2. 基本 值 类 型 


内 建 的 基本 映射 类 型 可 以 大 致 分 为 
integer, long, short, float, double, character, byte, boolean, yes_! 


这 些 类 型 都 对 应 Java 的 原始 类 型 或 者 其 封装 类 ， 来 符合 (特定 厂商 的 )SQL 字段 类 
型 。 boolean, yes_no 和 true_false 都 是 Java 中 boolean 或 
者 java.lang.Boolean 的 另外 说 法 。 


string 
从 java.lang.String 到 VARCHAR (或 者 Oracle 的 VARCHAR2 ) 的 映射 。 
date, time, timestamp 


从 java.util.Date 和 其 子 类 到 SQL 类 型 DATE ，TIME 和 TIMESTAMP (或 等 价 
类 型 ) 的 映射 。 


calendar, calendar_date 


从 java.util.Calendar 到 SQL 类 型 TIMESTAMP 和 DATE (或 等 价 类 型 ) 的 映 
射 。 


big decimal, big_integer 


从 java.math.BigDecimal 和 java.math.BigInteger 到 NUMERIC (或 者 
Oracle 的 NUMBER 类 型 ) 的 映射 。 


locale, timezone, currency 


从 java.util.Locale , java.util.TimeZone 和 java.util.Currency 
到 VARCHAR (或 者 Oracle 的 VARCHAR2 类 型 ) 的 映射 ,Locale 和 Currency 的 
实例 被 映射 为 它们 的 ISO 代码 。 TimeZone 的 实例 被 影射 为 它 的 ID 。 


class 


从 java.lang.Class 到 VARCHAR (2,4 Oracle 的 VARCHAR2 类 型 ) 的 映 
射 。 Class 被 映射 为 它 的 全 限定 名 。 


binary 

把 字 节 数组 (byte arrays) 映 射 为 对 应 的 SQL 二 进 制 类 型 。 
text 

把 长 Java 字 符 串 映射 为 SQL 的 CLOB 或 者 TEXT 类 型 。 
serializable 


把 可 序列 化 的 Java 类 型 映射 到 对 应 的 SQL 二 进 制 类 型 。 你 也 可 以 为 一 个 并 非 默认 为 
基本 类 型 的 可 序列 化 Java 类 或 者 接口 指定 Hibernate 类 型 serializable 。 


clob, blob 


JDBC 类 java.sql.Clob 和 java.sql.Blob 的 映射 。 某 些 程序 可 能 不 适合 使 
用 这 个 类 型 ， 因 为 blob 和 clob 对 象 可 能 在 一 个 事务 之 外 是 无 法 重用 的 。( 而 且 , 驱动 
程序 对 这 种 类 型 的 支持 充满 着 补丁 和 前 后 矛盾 。) 


imm_date, imm time, imm_timestamp, imm_calendar, imm_calendar_date, 


一 般 来 说 ， 上 映射 类 型 被 假定 为 是 可 变 的 Java 类 型 ， 只 有 对 不 可 变 Java 类 型 ， 
Hibernate 会 采取 特定 的 优化 措施 ， 应 用 程序 会 把 这 些 对 象 作为 不 可 变 对 象 处 理 。 比 
如 ， 你 不 应 该 对 作为 imm timestamp 映射 的 Date 执 行 Date.setTime() 。 要 改 
变 属性 的 值 ， 并 且 保 存 这 一 改变 ， 应 用 程序 必须 对 这 一 属性 重新 设置 一 个 新 的 (不 
一 样 的 ) AT Ro 


实体 及 其 集合 的 唯一 标识 可 以 是 除了 binary 、 blob 和 clob 之 外 的 任何 基 
础 类 型 。( 联 合 标识 也 是 允许 的 ， 后 面 会 说 到 。) 


在 org.hibernate.Hibernate 中 ， 定 义 了 基础 类 型 对 应 的 Type 常量 。 比 
如 ， Hibernate.STRING 代表 string 类 型 。 


5.2.3. 自 定 义 值 类 型 


开发 者 创建 属于 他 们 自己 的 值 类 型 也 是 很 容易 的 。 比 如 说 ， 你 可 能 硕 望 持久 

化 java.lang.BigInteger 类 型 的 属性 ， 持 久 化 成 为 VARCHAR 字段 。Hibernate 
没有 内 置 这 样 一 种 类 型 。 自 定义 类 型 能 够 映射 一 个 属性 (或 集合 元 素 ) 到 不 止 一 个 数 

据 库 表 字 段 。 比 如 说 ， 你 可 能 有 这 样 的 Java 属 性 : getName() / setName() ， 这 
是 java.lang.String 类 型 的 ， 对 应 的 持久 化 到 三 个 字段 : FIRST_NAME , 
INITIAL ， SURNAME 。 


要 实现 一 个 自 定 义 类 型 ， 可 以 实 

现 org.hibernate.UserType 或 org.hibernate.CompositeUserType 中 的 任 一 
个 ， 并 且 使 用 类 型 的 Java 全 限定 类 名 来 定义 属性 。 请 查 

看 org.hibernate.test.DoubleStringType 这 个 例子 ， 看 看 它 是 怎么 做 的 。 


<property name="twoStrings" type="org.hibernate.test.DoubleStrin 
gType"> 

<column name="first_string"/> 

<column name="Second_string"/> 
</property> 


注意 使 用 &lLt;column&gt;， 标签 来 把 一 个 属性 映射 到 多 个 字段 的 做 法 。 
CompositeUserType , EnhancedUserType , UserCollectionType ,和 
UserVersionType 接口 为 更 特殊 的 使 用 方式 提供 支持 。 


你 甚至 可 以 在 一 个 映射 文件 中 提供 参数 给 一 个 UserType 。 为 了 这 样 做 ， 你 
的 UserType 必须 实现 org.hibernate.usertype.ParameterizedType 接口 。 
为 了 给 自 定 义 类 型 提供 参数 ， 你 可 以 在 映射 文件 中 使 用 &1lt;type&gt; AÑ ° 


<property name="priority"> 
<type name="com.mycompany.usertypes.DefaultValueIntegerType" 


> 
<param name="default">0</param> 
</type> 
</property> 


现在 ， UserType 可 以 从 传 入 的 Properties 对 象 中 得 到 default 参数 的 值 。 


如 果 你 非常 频繁 地 使 用 某 一 UserType ， 可 以 为 他 定义 一 个 简称 。 这 可 以 通过 使 用 
&lt;typedefagt; 元 素来 实现 。Typedefs 为 一 自 定 义 类 型 赋予 一 个 名 称 ， 并 且 如 
果 此 类 型 是 参数 化 的 ， 还 可 以 包含 一 系列 默认 的 参数 值 。 


<typedef class="com.mycompany.usertypes.DefaultValueIntegerType" 
name="default_zero"> 


<param name="default">0</param> 
</typedef> 


<property name="priority" type="default_zero"/> 


ALT AIRE RAR R ANA ERR AT PO RAGA & typedef F RH KA © 


尽管 Hibernate 内 建 的 丰富 的 类 型 和 对 组 件 的 支持 意味 着 你 可 能 很 少 需要 使 用 自 定 
义 类 型 。 不 过 ， 为 那些 在 你 的 应 用 中 经 常 出 现 的 ( 非 实 体 ) 类 使 用 自 定 义 类 型 也 是 一 
个 好 方法 。 例 如 ， 一 个 MonetaryAmount 类 使 用 CompositeUserType 来 映射 是 
不 错 的 选择 ， 虽 然 他 可 以 很 容易 地 被 映射 成 组 件 。 这 样 做 的 动机 之 一 是 抽象 。 使 用 
自 定义 类 型 ， 以 后 假若 你 改变 表示 金额 的 方法 时 ， 它 可 以 保证 映射 文件 不 需要 修 
改 。 


5.3. 多 次 映射 同一 个 类 


对 特定 的 持久 化 类 ， 了 映射 多 次 是 允许 的 。 这 种 情形 下 ， 你 必须 指定 entity name 来 区 
别 不 同 映射 实体 的 对 象 实例 。 (默认 情况 下 ， 实 体 名 字 和 类 名 是 相同 的 。) 
Hibernate 在 操作 持久 化 对 象 、 编 写 查 询 条 件 ， 或 者 把 关联 映射 到 指定 实体 时 ， 允 许 
你 指定 这 个 entity name (实体 名 字 ) ° 


<class name="Contract" table="Contracts" 
entity-name="CurrentContract"> 


<set name="history" inverse="true" 
order -by="effectiveEndDate desc"> 
<key column="currentContractiId"/> 
<one-to-many entity-name="HistoricalContract"/> 
</set> 
</class> 


<class name="Contract" table="ContractHistory" 
entity-name="HistoricalContract"> 


<many-to-one name="CurrentContract" 
column="currentContractId" 
entity-name="CurrentContract"/> 
</class> 


注意 这 里 关联 是 如 何 用 entity-name 来 代替 class 的 。 


5.4. SQL 中 引号 包围 的 标识 符 


你 可 通过 在 映射 文档 中 使 用 反 向 引号 

( ) 把 表 名 或 者 字段 名 包围 起 来 ， 以 强制 Hibernate 在 生成 的 SQL 中 把 标识 符 用 引号 包围 起 来 
Dialect (方言 ) 来 使 用 正确 的 引号 风格 (通常 是 双 引 号 ， 但 是 在 SQL Server 中 是 括 
号 ，MySQL 中 是 反 向 引号 )。 


<class name="LineItem" table="`Line Item "> 

<id name="id" column=" Item Id "/><generator class="assigned 
"/></id> 

<property name="itemNumber" column=" Item #`"/> 


</class> 


5.5. 其 他 元 数据 (Metadata) 


XML 并 不 适用 于 所 有 人 , 因此 有 其 他 定义 Hibernate O/R 映射 元 数据 (metadata) 的 方 
法 。 


5.5.1. 使 用 XDoclet 标记 


很 多 Hibernate 使 用 者 更 喜欢 使 用 XDoclet @hibernate.tags 将 映射 信息 直接 上 获 入 
到 源 代 码 中 。 我 们 不 会 在 本 文档 中 涉及 这 个 方法 ， 因 为 严格 说 来 ， 这 属于 XDoclet 
的 一 部 分 。 然 而 ， 我 们 包含 了 如 下 使 用 XDoclet 映 射 的 cat 类 的 例子 。 


package eg; 
import java.util.Set; 
import java.util.Date; 


Vas 
* @hibernate.class 
* table="CATS" 
a 
public class Cat { 
private Long id; // identifier 
private Date birthdate; 
private Cat mother; 
private Set kittens 
private Color color; 
private char sex; 
private float weight; 


JER 
* @hibernate.id 
* generator-class="native" 
* column="CAT_ID" 
2 
public Long getId() { 
return id; 


} 

private void setId(Long id) { 
this.id=id; 

} 

[ese 


* @hibernate.many-to-one 
* ~column="PARENT_ID" 
a 
public Cat getMother() { 
return mother; 
} 


void setMother(Cat mother) { 
this.mother = mother; 
} 


JAS 
* @hibernate.property 
* column="BIRTH_DATE" 


ays 
public Date getBirthdate() { 
return birthdate; 
} 
void setBirthdate(Date date) { 
birthdate = date; 
} 


[fess 
* @hibernate. property 
* ~column="WEIGHT" 
we 
public float getWeight() { 
return weight; 


void setWeight(float weight) { 
this.weight = weight; 
} 


JRS 
* @hibernate.property 
* column="COLOR" 
* not-null="true" 
SJA 
public Color getColor() { 
return color; 


void setColor(Color color) { 
this.color = color; 
} 


JER 
* @hibernate.set 
* inverse="true" 
* order -by="BIRTH_DATE" 
* @hibernate.collection-key 
* ~column="PARENT_ID" 
* @hibernate.collection-one-to-many 
EA 
public Set getKittens() { 
return kittens; 
} 


void setKittens(Set kittens) { 
this.kittens = kittens; 
} 


// addKitten not needed by Hibernate 
public void addKitten(Cat kitten) { 
kittens.add(kitten); 


} 
fers 
* @hibernate.property 
* column="SEX" 
* not-null="true" 
* 


update="false" 


oye 
public char getSex() { 
return sex; 


void setSex(char sex) { 
this.sex=sex; 
} 


参考 Hibernate 网 站 更 多 的 Xdoclet 和 Hibernate 的 例子 


5.5.2. 使 用 JDK 5.0 的 注解 (Annotation) 


JDK 5.0 在 语言 级 别 引 入 了 XDoclet 风格 的 标注 ， 并 且 是 类 型 安全 的 ， 在 编译 期 进 
行 检查 。 这 Hua 比 XDoclet 的 注解 更 为 强大 ， 有 更 好 的 工具 和 |DE 支 持 。 例 如 ， 
IntelliJ IDEA， 支 持 JDK 5.0 注 解 的 自动 完成 和 语法 高 亮 。EJB 规 范 的 新 修订 版 
(JSR-220) 使 用 JDK 5.0 的 注解 作为 entity beans 的 Al dl a o 
Hibernate 3 实现 了 JSR-220 (the persistence APIN) 的 EntityManager ， 支 持 通 过 
Hibernate Annotations 包 定义 映射 元 数据 。 这 个 包 作 为 单独 的 部 分 下 载 ， 支 持 EJB3 
(JSR-220) 和 Hibernate3 的 元 数据 。 


这 是 一 个 被 注解 为 EJB entity bean 的 POJO 类 的 例子 


@Entity(access = AccessType.FIELD) 
public class Customer implements Serializable { 


@Id; 
Long id; 


String firstName; 
String lastName; 
Date birthday; 


@Transient 
Integer age; 


@Embedded 
private Address homeAddress; 


@OneToMany(cascade=CascadeType.ALL) 
@JoinColumn(name="CUSTOMER_ID" ) 
Set<Order> orders; 


// Getter/setter and business methods 


注意 : 对 IDK 5.0 注解 (和 JSR-220) 支 持 的 工作 仍然 在 进行 中 ,并 未 完成 。 更 多 细 
节 请 参阅 Hibernate Annotations 模块 。 


5.6. 数据 库 生 成 属性 (Generated Properties ) 


Generated properties 指 的 是 其 值 由 数据 库 生 成 的 属性 。 一 般 来 说 ， 如 果 对 象 有 任 

何 属 性 由 数据 库 生 成 值 ，Hibernate 应 用 程序 需要 进行 刷新 (refresh) 。 但 如 果 把 
属性 标明 为 generated， 就 可 以 转 由 Hibernate 来 负责 这 个 动作 。 实 际 上 。 对 定义 了 
generated properties 的 实体 ,每 当 Hibernate 执 行 一 条 SQL INSERT 或 者 UPDATE 语 
多， 会 立刻 执行 一 条 select 来 获得 生成 的 值 。 


被 标明 为 generated 的 属性 还 必须 是 non-insertable 和 non-updateable 的 。 只 有 第 
5.1.7 节 “ 版 本 (version) (可 选 ”， 第 5.1.8 节 “timestamp (可 选 ” 和 第 5.1.9 节 
“property "可 以 被 标明 为 generated。 


never (默认 ) 标明 此 属性 值 不 是 从 数据 库 中 生成 。 


insert -标明 此 属性 值 在 insert 的 时 候 生 成 ， 但 是 不 会 在 随后 的 update 时 重新 生 
成 。 比 如 说 创建 日 期 就 归属 于 这 类 。 注 意 虽 然 第 5.1.7 7 “版 本 (version) (可 
选 Pp 和 第 5.1.8 节 “timestamp (可 选 )" 属 性 可 以 被 标注 为 generated， 但 是 不 适用 这 
个 选项 ... 


always - 标明 此 属性 值 在 insert 和 update 时 都 会 被 生成 。 


5.7. 辅助 数据 库 对 象 (Auxiliary Database Objects) 


Allows CREATE and DROP of arbitrary database objects, in conjunction with 
Hibernate's schema evolution tools, to provide the ability to fully define a user 
schema within the Hibernate mapping files. Although designed specifically for 
creating and dropping things like triggers or stored procedures, really any SQL 
command that can be run viaa java.sql.Statement.execute() method is 
valid here (ALTERs, INSERTS, etc). There are essentially two modes for defining 
auxiliary database objects... 帮助 CREATE 和 DROP 任 意 数据 库 对 象 ， 与 Hibernate 
的 Schema 交互 工具 组 合 起 来 ， 可 以 提供 在 Hibernate 了 映射 文件 中 完全 定义 用 户 
schema 的 能 力 。 虽 然 这 是 为 创建 和 销毁 trigger( 触 发 器 ) 或 stored procedure( 存 储 
过 程 ) 等 特别 设计 的 ， 实 际 上 任何 可 以 在 java.sql.Statement.execute() 方法 
中 执行 的 SQL 命令 都 可 以 在 此 使 用 (比如 ALTER, INSERT， 等 等 ) 。 本 质 上 有 两 种 
模式 来 定义 辅助 数据 库 对 象 … 


第 一 种 模式 是 在 映射 文件 中 显 式 声明 CREATE 和 DROP 命 令 : 


<hibernate-mapping> 


<database-object> 
<create>CREATE TRIGGER my_trigger ...</create> 
<drop>DROP TRIGGER my_trigger</drop> 
</database-object> 
</hibernate-mapping> 


第 二 种 模式 是 提供 一 个 类 ， 这 个 类 知道 如 何 组 织 CREATE 和 DROP 命 令 。 这 个 特别 
类 必须 实现 org. hibernate.mapping.AuxiliaryDatabaseObject 接口 。 


<hibernate-mapping> 


<database-object> 
<definition class="MyTriggerDefinition"/> 
</database-object> 
</hibernate-mapping> 


还 有 ， 这 些 数据 库 对 象 可 以 特别 指定 为 仅 在 特定 的 方言 中 才 使 用 。 


<hibernate-mapping> 


<database-object> 
<definition class="MyTriggerDefinition"/> 
<dialect-scope name="org.hibernate.dialect.Oracle9Dialec 
t"/> 
<dialect-scope name="org.hibernate.dialect.OracleDialect 
"7/> 
</database-object> 
</hibernate-mapping> 
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. 集合 例子 (Collection example) 


6.1. 持久 化 集合 类 (Persistent collections) 


<a Class="calibre5 pcalibre pcalibre1" id="collections-persistent-translate- 
comment"></a>( 译 者 注 : 在 阅读 本 章 的 时 候 ， 以 后 整个 手册 的 阅读 过 程 中 ， 我 们 都 
会 面临 一 个 名 词 方面 的 问题 ， 那 就 是 “集合 "。"Collections" 和 "Set" 在 中 文 里 对 应 都 
被 翻译 为 “集合 "， 但 是 他 们 的 含义 很 不 一 样 。Collections 是 一 个 超 集 ，Set 是 其 中 的 
一 种 。 大 部 分 情况 下 ， 本 译 稿 中 泛 指 的 未 加 英文 注 明 的 "集合"， 都 应 当 理解 

为 “Collections”"。 在 有 些 二 者 同时 出 现 ， 可 能 造成 混淆 的 地 方 ， 我 们 用 “集合 类 "来 特 
4“Collecions”, "集合 (Set)" 来 指 "Set"， 一 般 都 会 在 后 面 的 括号 中 给 出 英文 。 硕 望 大 
家 在 阅读 时 联系 上 下 文理 解 ， 不 要 造成 误解 。 与 此 同时 ， "元 素 " 一 词 对 应 的 英 

文 “element?， 也 有 两 个 不 同 的 含义 。 其 一 为 集合 的 元 素 ， 是 内 存 中 的 一 个 变量 ; 另 
一 含义 则 是 XML 文档 中 的 一 个 标签 所 代表 的 元 素 。 也 请 注意 区 别 。 本 章 中 ,特别 是 
后 半 部 分 是 需要 反复 阅读 才能 理解 清楚 的 。 如 果 遇 到 任何 疑问 ,请 记 住 ,英文 版 本 的 
reference 是 惟一 标准 的 参考 资料 。) 


Hibernate Rit AL FSF ALA BMW AGO > rete: 


public class Product { 
private String serialNumber; 
private Set parts = new HashSet(); 


public Set getParts() { return parts; } 

void setParts(Set parts) { this.parts = parts; } 

public String getSerialNumber() { return serialNumber; } 
void setSerialNumber(String sn) { serialNumber = sn; } 


实际 的 接口 可 能 是 java.util.Set , java.util.Collection 
java.util.List , java.util.Map , java.util.SortedSet 
java.util.SortedMap 或 者 ... 任 何 你 喜欢 的 类 型 1 ("任何 你 喜欢 的 类 型 " 代表 你 
需要 编写 org.hibernate.usertype.UserCollectionType 的 实现 .) 


注意 我 们 是 如 何 用 一 个 HashSet 实例 来 初始 化 实例 变量 的 .这 是 用 于 初始 化 新 创建 
(尚未 持久 化 ) 的 类 实例 中 集合 值 属 性 的 最 佳 方法 。 当 你 持久 化 这 个 实例 时 比如 
通过 调用 persist() 一 一 Hibernate 会 自动 把 HashSet 替换 为 Hibernate 自 己 

的 Set 实现 。 观 察 下 面 的 错误 : 





Cat cat = new DomesticCat(); 
Cat kitten = new DomesticCat(); 


Set kittens = new HashSet(); 

kittens.add(kitten); 

cat.setKittens(kittens); 

session.persist(cat); 

kittens = cat.getKittens(); //Okay, kittens collection is a Set 
(HashSet) cat.getKittens(); //Error! 


根据 不 同 的 接口 类 型 ， 被 Hibernate 注 射 的 持久 化 集合 类 的 表现 类 似 HashMap , 
HashSet , TreeMap , TreeSet or ArrayList ° 


集合 类 实例 具有 值 类 型 的 通常 行为 。 当 被 持久 化 对 象 引 用 后 ， 他 们 会 自动 被 持久 
化 ， 当 不 再 被 引用 后 ， 自 动 被 删除 。 人 假若 实 例 被 从 一 个 持久 化 对 象 传递 到 另 一 个 ， 
它 的 元 素 可 能 从 一 个 表 转 移 到 另 一 个 表 。 两 个 实体 不 能 共享 同一 个 集合 类 实例 的 引 
用 。 因 为 底层 关系 数据 库 模 型 的 原因 ， 集 合 值 属性 无 法 支持 空 值 语义 ; Hibernate 对 
空 的 集合 引用 和 空 集合 不 加 区 别 。 


你 不 需要 过 多 的 为 此 担心 。 就 如 同 你 平时 使 用 首 通 的 Java 集 合 类 一 样 来 使 用 持久 化 
集合 类 。 只 是 要 确认 你 理解 了 双向 关联 的 语义 (a Lite) 。 


6.2. 集合 映射 ( Collection mappings ) 


用 于 映射 集合 类 的 Hibernate 了 映射 元 素 取 决 于 接口 的 类 型 。 比 如 ， 
元 素 用 来 映射 Set 类 型 的 属性 。 


<cla 


</cl 


SS name="Product"> 


&lt;set&gt; 


<id name="serialNumber" column="productSerialNumber"/> 


<set name="parts"> 


<key column="productSerialNumber" not-null="true"/> 


<one-to-many class="Part"/> 
</set> 
ass> 


除了 @lt;setagt; ,还 有 &lt;list&gt; , &lt;map&gt; , &lt;bag&gt; , 
&lt;array&gt; 和 &lt;primitive-array&gt; 了 映射 元 素 。 &lt;mapagt; 


有 代表 ， 


<map 


ezorn 


BE: 


name="propertyName" 
table="table_name" 
schema="schema_name" 
lazy="true|extra|false" 
inverse="true| false" 


cascade="all|none|save-update|delete|all-delete-orphan|delet 


phan" 
sort="unsorted|natural|comparatorClass" 
order -by="column_name asc|desc" 
where="arbitrary sql where condition" 
fetch="join|select |subselect" 
batch-size="N" 
access="field|property|ClassName" 
optimistic-lock="true|false" 
mutable="true|false" 
node="element-name]|." 
embed-xml="true|false" 


<key .... /> 
<map-key .... /> 
<element .... /> 


</map> 


E 


FN 


name 集合 属性 的 名 称 


table (可 选 一 一 默认 为 属性 的 名 称 ) 这 个 集合 表 的 名 称 ( 不 能 在 一 对 多 
的 关联 关系 中 使 用 ) 

schema (可 选 ) 表 的 Schema 的 名 称 , 他 将 覆盖 在 根 元 素 中 定义 的 schema 
lazy (可 选 -- 默 认为 true) 可 以 用 来 关闭 延迟 加 载 (false)， 指 定 一 直 使 用 预 


先 抓 取 , 或 者 打开 "extra-lazy" 抓 取 ， 此 时 大 多 数 操作 不 会 初始 化 集合 类 (适用 
于 非常 大 的 集合 ) 


inverse (可 选 一 默认 为 false ) 标记 这 个 集合 作为 双向 关联 关系 中 的 
方向 一 端 。 

cascade (可 选 一 一 默认 为 none ) 让 操作 级 联 到 子 实体 

sort (可 选 ) 指 定 集合 的 排序 顺序 , 其 可 以 为 自然 的 ( natural ) 或 者 给 定 一 
个 用 来 比较 的 类 。 

order-by (可 选 , 仅 用 于 jdk1.4) 指定 表 的 字段 (一 个 或 几 个 ) 再 加 上 asc 或 者 
desc( 可 选 ) 定义 Map,Set 和 Bag 的 迭代 顺序 


where (可 选 ) 指定 任意 的 SQL where 条 件 , 该 条 件 将 在 重新 载 入 或 者 删除 
这 个 集合 时 使 用 ( 当 集 合 中 的 数据 仅仅 是 所 有 可 用 数据 的 一 个 子 集 时 这 个 条 件 
非常 有 用 ) 


meee po: KIA select ) 用 于 在 外 连接 抓 取 、 通 过 后 续 select 抓 取 
和 通过 后 续 subselect 抓 取 之 间 选 择 。 
batch-size (可 选 , RUA 1 ) 指定 通过 延迟 加 载 取得 集合 实例 的 批 处 理 


块 大 小 ("batch size") 。 


access (可 选 -默认 为 属性 property):Hibernate 取 得 集合 属性 值 时 使 用 的 策 
略 

乐观 锁 (可 选 - 
实体 的 版 本 增长 。( 对 一 对 多 关联 来 说 ， 关 闭 这 个 属性 常常 是 有 理 的 ) 


mutable( 可 变 ) (可 选 - 默认 为 ): 若 值 为 false ,表明 集合 中 的 元 
素 不 会 改变 (在 某 些 情况 下 可 以 进行 一 些小 的 性 能 优化 ) 。 


6.2.1. 集合 外 键 (Collection foreign keys) 
集合 实例 在 数据 库 中 依靠 持 有 集合 的 实体 的 外 键 加 以 状 别 。 此 外 键 作为 集合 关键 字 


ft (collection key column) (或 多 个 字段 ) 加 以 引用 。 集 合 关键 字段 通 
过 &lt:key&gt; 元 素 映 射 。 


在 外 键 字段 上 可 能 具有 非 空 约束 。 对 于 大 多 数 集合 来 说 ， 这 是 隐 爹 的。 对 单 向 一 对 
多 关联 来 说 ， 外 键 字 段 默 认 是 可 以 为 空 的 ， 因 此 你 可 能 需要 指明 
not-null="true" œ 


<key column="productSerialNumber" not-null="true"/> 


外 键 约束 可 以 使 用 ON DELETE CASCADE ° 


<key column="productSerialNumber" on-delete="cascade"/> 


对 &lt;key&gt; 元 素 的 完整 定义 ， 请 参阅 前 面 的 章节 。 


6.2.2. 247% (Collection elements ) 


集合 几乎 可 以 包含 任何 其 他 的 Hibernate 类 型 ， 包 括 所 有 的 基本 类 型 、 自 定义 类 型 、 
组 件 ， 当 然 还 有 对 其 他 实体 的 引用 。 存 在 一 个 重要 的 区 别 : 位 于 集合 中 的 对 象 可 能 
是 根据 " 值 " 语 义 来 操作 〈 其 声明 周期 完全 依赖 于 集合 持 有 者 ) ， 或 者 它 可 能 是 指向 
另 一 个 实体 的 引用 ， 具 有 其 自己 的 生命 周期 。 在 后 者 的 情况 下 ， 被 作为 集合 持 有 的 
状态 考虑 的 ， 只 有 两 个 对 象 之 间 的 “连接 " 。 


被 包容 的 类 型 被 称 为 集合 元 素 类 型 (collection element type) 。 集 合 元 素 通 

过 @lt;element&gt; 或 &lt;composite-elementagt; 了 映射， 或 在 其 是 实体 引 
用 的 时 候 ， 通 过 &lt;one-to-many&gt; 或 &lt;many-to-manyagt; 映射 。 前 两 
种 用 于 使 用 值 语 义 映 射 元 素 ， 后 两 种 用 于 映射 实体 关联 。 


6.2.3. 索引 集合 类 (Indexed collections) 


所 有 的 集合 映射 ， 除 了 set 和 bag 语 义 的 以 外 ， 都 需要 指定 一 个 集合 表 的 索引 字段 

(index column) 一 一 用 于 对 应 到 数组 索引 ， 或 者 List 的 索引 ， 或 者 Hap 的 关键 
字 。 通 过 @lt;map-key&gt; , Map 的 索引 可 以 是 任何 基础 类 型 ; 若 通 

过 &lt;map-key-many-to-many&gt; ， 它 也 可 以 是 一 个 实体 引用 ; 若 通 

过 &lt;composite-map-key&gt; ， 它 还 可 以 是 一 个 组 合 类 型 。 数 组 或 列表 的 索 
引 必 须 是 integer 类 型 ， 并 且 使 用 &lt;list-index&egt; THC LIRA o Har 
射 的 字段 包含 有 顺序 排列 的 整数 (默认 从 0 开始 ) 。 


<map - key 
column="column_name" 
formula="any SQL expression" 
type="type_name" 
node="@attribute-name" 
length="N"/> 


0 column (可 选 ): 保 存 集合 索引 值 的 字段 名 。 


@ formula (可 选 ): 用 于 计算 map 关 键 字 的 SQL 公式 
© type (必须 ): 映 射 键 (map key) 的 类 型 。 


<map-key-many-to-many 
column="column_name" 
formula="any SQL expression" 
class="ClassName" 


0 column (可 选 ): 集 合 索引 值 中 外 键 字 段 的 名 称 

@ formula (可 选 ): 用 于 计算 map 关 键 字 的 外 键 的 SQL 公 式 

© class (必需 ): 映 射 的 键 (map key) 使 用 的 实体 类 。 

假若 你 的 表 没 有 一 个 索引 字段 , 当 你 仍然 希望 使 用 List 作为 属性 类 型 ,你 应 该 把 此 


属 性 映射 为 Hibernate <bag>。 从 数据 库 中 获取 的 时 候 ，bag 不 维护 其 顺序 ， 但 也 可 
选择 性 的 进行 排序 。 


从 集合 类 可 以 产生 很 大 一 部 分 映射 ， 零 盖 了 很 多 常见 的 关系 模型 。 我 们 建议 你 试验 
schema 生 成 工具 ， 来 体会 一 下 不 同 的 映射 声明 是 如 何 被 翻译 为 数据 库 表 的 。 


6.2. 集合 映射 〈 Collection mappings ) 
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6.2.4. 值 集合 于 多 对 多 关联 (Collections of values 
and many-to-many associations) 


任何 值 集合 或 者 多 对 多 关联 需要 专用 的 具有 一 个 或 多 个 外 键 字段 的 collection 
table、 一 个 或 多 个 collection element column ， 以 及 还 可 能 有 一 个 或 多 个 索引 字 
段 。 


对 于 一 个 值 集 合 , 我 们 使 用 &lt;element&gt; 标签 。 


<element 
column="column_name" 
formula="any SQL expression" 
type="typename" 
length="L" 
precision="P" 
scale="S" 
not-null="true|false" 
unique="true|false" 
node="element -name" 


/> 

0 column (可 选 ): 保 存 集合 元 素 值 的 字段 名 。 
@ formula (T) 用 于 计算 元 素 的 SQL 公式 
© type (必需 ): 集 合 元 素 的 类 型 


多 对 多 关联 (many-to-many association) 使 用 &lt;many-to-many&gt; 元 素 定 义 . 


<many-to-many 
column="column_name" 
formula="any SQL expression" 
class="ClassName" 
fetch="select|join" 
unique="true|false" 
not -found="ignore|exception" 
entity-name="EntityName" 
property-ref="propertyNameFromAssociatedClass" 
node="element -name" 
embed-xml="true|false" 

/> 


© column (可 选 ): 这 个 元 素 的 外 键 关 键 字 段 名 
@ formula (可 选 ): 用 于 计算 元 素 外 键 值 的 SQL 公式 . 
© class (必需 ): 关联 类 的 名 称 


outer-join (可 选 - 默认 为 auto ): 在 Hibernate 系 统 参数 
© 中 hibernate.use outer _ join 被 打开 的 情况 下 ,该 参数 用 来 允许 使 用 
outer join 来 载 入 此 集合 的 数据 。 


为 此 关联 打开 外 连接 抓 取 或 者 后 续 select 抓 取 。 这 是 特殊 情况 ; 对 于 一 个 实 
o 体 及 其 指向 其 他 实体 的 多 对 多 关联 进 全 预先 抓 取 〈 使 用 一 条 单独 

的 SELECT )， 你 不 仅 需 要 对 集合 自身 打开 join ， 也 需要 

对 @lt;many-to-many&gt; %SARLAA ALBEE © 


对 外 键 字段 允许 DDL 生 成 的 时 候 生成 一 个 惟一 约束 。 这 使 关联 变 成 了 一 个 高 
© 效 的 一 对 多 关联 。 (WAR: 原 aT makes the association 
multiplicity effectively one to many.) 


not-found (可 选 - 默认 为 exception ): 指明 引用 的 外 键 中 缺少 某 些 行 
该 如 何 处 理 : ignore 会 把 缺失 的 行 作为 一 个 空 引 用 处 理 。 


@ entity-name (可 选 ): 被 关联 的 类 的 实体 名 ， 作 为 class 的 替代 。 


@ property-ref : (可 选 ) 被 关联 到 此 外 键 (foreign key) 的 类 中 的 对 应 属性 的 
字 。 若 未 指定 ， 使 用 被 关联 类 的 主键 。 
例子 : 首先 , 一 组 字符 串 : 


<set name="names" table="NAMES"> 

<key column="GROUPID"/> 

<element column="NAME" type="string"/> 
</set> 


包含 一 组 整数 的 bag( 还 设置 了 order-by 参数 指定 了 和 迭代 的 顺序 ) : 


<bag name="sizes" 
table="item_sizes" 
order-by="size asc"> 
<key column="item_id"/> 
<element column="size" type="integer"/> 
</bag> 


一 个 实体 数组 ,在 这 个 案例 中 是 一 个 多 对 多 的 关联 (注意 这 里 的 实体 是 自动 管理 生命 
周期 的 对 象 (lifecycle objects) , cascade="all" ): 


<array name="addresses" 
table="PersonAddress" 
cascade="persist"> 
<key column="personId"/> 
<list-index column="sortOrder"/> 
<many-to-many column="addressId" class="Address"/> 
</array> 


一 个 map, 通 过 字符 串 的 索引 来 指明 日 期 : 


<map name="holidays" 
table="holidays" 
schema="dbo" 
order -by="hol_name asc"> 
<key column="id"/> 
<map-key column="hol_name" type="string"/> 
<element column="hol_date" type="date"/> 
</map> 


一 个 组 件 的 列表 : (下 一 章 讨论 ) 


<list name="carComponents" 
table="CarComponents"> 
<key column="carId"/> 
<list-index column="sortOrder"/> 
<composite-element class="CarComponent"> 
<property name="price"/> 
<property name="type"/> 
<property name="SerialNumber" column="sSerialNum"/> 
</composite-element> 
</list> 


6.2.5. —*t 4 HK (One-to-many Associations ) 


一 对 多 关联 通过 外 键 连接 两 个 类 对 应 的 表 , 而 没有 中 间 集 合 表 。 这 个 关系 模型 失 
去 了 一 些 Java 集 合 的 语义 : 


© 一 个 被 包含 的 实体 的 实例 只 能 被 包含 在 一 个 集合 的 实例 中 
© 一 个 被 包含 的 实体 的 实例 只 能 对 应 于 集合 索引 的 一 个 值 中 


一 个 从 Product 到 Part 的 关联 需要 关键 字 字 段 ,可 能 还 有 一 个 索引 字段 指 
向 Part 所 对 应 的 表 。 &lt;one-to-manyagt; 标记 指明 了 一 个 一 对 多 的 关联 。 


<one-to-many 
class="ClassName" 
not-found="ignore|exception" 
entity-name="EntityName" 
node="element-name" 
embed-xml="true|false" 
/> 


@ class (必须 ): 被 关联 类 的 名 称 。 


not -found (可 选 - 默认 为 exception ): 指明 若 缓存 的 标示 值 关联 的 行 缺 
失 , 该 如 何 处 理 : ignore 会 把 缺失 的 行 作为 一 个 空 关 联 处 理 。 


© entity-name (可 选 ): 被 关联 的 类 的 实体 名 ， 作 为 class 的 替代 。 
例子 


<set name="bars"> 

<key column="foo_id"/> 

<one-to-many class="org.hibernate.Bar"/> 
</set> 


注意 ; &@lt;one-to-many&gt; 元 素 不 需要 定义 任何 字段 。 也 不 需要 指定 表 名 。 


重要 提示 :如 果 一 对 多 关联 中 的 外 键 字段 定义 成 NOT NULL ,你 必须 
把 &lt;keyagt; 映射 声明 为 not-null="true" ,或 者 使 用 双向 关联 ， 并 且 标 
明 inverse="true" 。 参 阅 本 章 后 面 关于 双向 关联 的 讨论 。 


下 面 的 例子 展示 一 个 Part 实体 的 map, 把 name 作 为 关键 字 。( partName 
是 Part 的 持久 化 属性 )。 注 意 其 中 的 基于 公式 的 索引 的 用 法 。 


<map name="parts" 
cascade="all"> 
<key column="productId" not-null="true"/> 
<map-key formula="partName"/> 
<one-to-many class="Part"/> 
</map> 


6.3. 高 级 集合 映射 (Advanced collection 
mappings ) 


6.3.1. 有 序 集 合 (Sorted collections ) 


Hibernate 支 持 实现 java.util.SortedMap 和 java.util.SortedSet 的 集合 。 
你 必须 在 映射 文件 中 指定 一 个 比较 器 : 


<set name="aliases" 
table="person_aliases" 
sort="natural"> 
<key column="person"/> 
<element column="name" type="string"/> 
</set> 


<map name="holidays" sort="my.custom.HolidayComparator"> 
<key column="year_id"/> 
<map-key column="hol_name" type="string"/> 
<element column="hol_date" type="date"/> 

</map> 


sort 属性 中 允许 的 值 包 括 unsorted , natural 和 某 个 实现 
J java.util.Comparator 的 类 的 名 称 。 


分 类 集合 的 行为 事实 上 象 java.util.Treeset 或 者 java.util.TreeMap ° 


如 果 你 希望 数据 库 自己 对 集合 元 素 排 序 ， 可 以 利用 set ，bag 或 者 map 映射 中 
的 order-by 属性 。 这 个 解决 方案 只 能 在 jdk1.4 或 者 更 高 的 jdk 版 本 中 才 可 以 实现 
(通过 LinkedHashSet 或 者 LinkedHashMap 实 现 )。 它 是 在 SQL 查询 中 完成 排序 ， 而 
不 是 在 内 存 中 。 


<Set name="aliases" table="person_aliases" order-by="lower (name) 
asc"> 

<key column="person"/> 

<element column="name" type="string"/> 
</set> 


<map name="holidays" order-by="hol_date, hol_name"> 
<key column="year_id"/> 
<map-key column="hol_name" type="string"/> 
<element column="hol_date" type="date"/> 

</map> 


注意 : 这 个 order-by 属性 的 值 是 一 个 SQL 排 序 子 句 而 不 是 HQL 的 ! 


we 


关联 还 可 以 在 运行 时 使 用 集合 filter() 根据 任意 的 条 件 来 排序 。 


sortedUsers = s.createFilter( group.getUsers(), "order by this.n 
ame" ).list(); 


6.3.2. 双向 关联 (Bidirectional associations ) 


双向 关联 允许 通过 关联 的 任 一 端 访问 另外 一 端 。 在 Hibernate 中 , 支持 两 种 类 型 的 双 
向 关联 : 


一 对 多 (one-to-many ) 

Set 或 者 bag 值 在 一 端 , 单独 值 ( 非 集合 ) 在 另外 一 端 
多 对 多 (many-to-many ) 

两 端 都 是 set 或 bag 值 


要 建立 一 个 双向 的 多 对 多 关联 ， 只 需要 映射 两 个 many-to-many 关 联 到 同一 个 数据 库 
表 中 ， 并 再 定义 其 中 的 一 端 为 jinverse( 使 用 哪 一 端 要 根据 你 的 选择 ， 但 它 不 能 是 一 
个 索引 集合 )。 


这 里 有 一 个 many-to-many 的 双向 关联 的 例子 ;每 一 个 category 都 可 以 有 很 多 items, 每 
一 个 items 可 以 属于 很 多 categories : 


<class name="Category"> 
<id name="id" column="CATEGORY_ID"/> 


<bag name="items" table="CATEGORY_ITEM"> 
<key column="CATEGORY_ID"/> 
<many-to-many class="Item" column="ITEM_ID"/> 
</bag> 
</class> 


<class name="Item"> 
<id name="id" column="CATEGORY_ID"/> 


<!-- inverse end --> 
<bag name="categories" table="CATEGORY_ITEM" inverse="true"> 
<key column="ITEM_ID"/> 
<many-to-many class="Category" column="CATEGORY_ID"/> 
</bag> 
</class> 


如 果 只 对 关联 的 反 向 端 进 行 了 改变 ， 这 个 改变 不 会 被 持久 化 。 这 表示 Hibernate 为 
每 个 双向 关联 在 内 存 中 存在 两 次 表现 ,一 个 从 A 连接 到 B, 另 一 个 从 B 连 接 到 A。 如 果 你 
回想 一 下 Java 对 象 模型 ， 我 们 是 如 何在 Java 中 创建 多 对 多 关系 的 ， 这 可 以 让 你 更 容 
H 7 

易 理 解 : 


category.getItems().add(item); // The category now "kno 
ws" about the relationship 

item.getCategories().add(category); // The item now "knows" 
about the relationship 


session.persist(item); // The relationship won 
''t be saved! 
session.persist(category); // The relationship wil 


1 be saved 


非 反 向 端 用 于 把 内 存 中 的 表示 保存 到 数据 库 中 。 


要 建立 一 个 一 对 多 的 双向 关联 ， 你 可 以 通过 把 一 个 一 对 多 关联 ， 作 为 一 个 多 对 一 关 
联 映射 到 到 同一 张 表 的 字段 上 ， 并 且 在 "多 "的 那 一 端 定义 inverse="true" 。 


<class name="Parent"> 
<id name="id" column="parent_id"/> 


<set name="children" inverse="true"> 
<key column="parent_id"/> 
<one-to-many class="Child"/> 
</set> 
</class> 


<class name="Child"> 
<id name="id" column="child_id"/> 


<many-to-one name="parent" 
class="Parent" 
column="parent_id" 
not -null="true"/> 
</class> 


在 "一 ”这 一 端 定义 inverse="true" 不 会 影响 级 联 操作 ， 二 者 是 正 交 的 概念 ! 


6.3.3. 双向 关联 ， 涉 及 有 序 集合 类 


对 于 有 一 端 是 &lt;list&gt; 或 者 &1lt;map&gt; 的 双向 关联 ， 需 要 加 以 特别 考 
虑 。 假 若 子 类 中 的 一 个 属性 映射 到 索引 字段 ， 没 问题 ， 我 们 仍然 可 以 在 集合 类 映射 
上 使 用 inverse="true" 


<class name="Parent"> 
<id name="id" column="parent_id"/> 


<map name="Children" inverse="true"> 
<key column="parent_id"/> 
<map-key column="name" 
type="string"/> 
<one-to-many class="Child"/> 
</map> 
</class> 


<class name="Child"> 
<id name="id" column="child_id"/> 


<property name="name" 
not -null="true"/> 
<many-to-one name="parent" 
class="Parent" 
column="parent_id" 
not -null="true"/> 
</class> 


但 是 ， 假 若 子 类 中 没有 这 样 的 属性 存在 ， 我 们 不 能 认为 这 个 关联 是 昌 正 的 双向 关联 
aa ， 在 关联 的 一 端 有 一 些 另 外 一 端 没 有 的 信息 ) 。 在 这 种 情况 下 ， 我 们 
能 使 用 inverse="true" 。 我 们 需要 这 样 用 : 


<class name="Parent"> 
<id name="id" column="parent_id"/> 


<map name="children"> 
<key column="parent_id" 
not -null="true"/> 
<map-key column="name" 
type="string"/> 
<one-to-many class="Child"/> 
</map> 
</class> 


<class name="Child"> 
<id name="id" column="child_id"/> 


<many-to-one name="parent" 
class="Parent" 
column="parent_id" 
insert="false" 
update="false" 
not -null="true"/> 
</class> 


注意 在 这 个 映射 中 ， 关 联 中 集合 类 " 值 " 一 端 负责 来 更 新 外 键 .TODO: Does this really 
result in some unnecessary update statements? 


6.3.4. 三 重 关 联 (Ternary associations ) 


有 三 种 可 能 的 途径 来 映射 一 个 三 重 关联 。 第 一 种 是 使 用 一 个 Map ， 把 一 个 关联 作 
为 其 索引 : 


<map name="contracts"> 
<key column="employer_id" not-null="true"/> 
<map-key-many-to-many column="employee_id" class="Employee"/ 
> 
<one-to-many class="Contract"/> 
</map> 


<map name="connections"> 

<key column="incoming_node_id"/> 

<map-key-many-to-many column="outgoing_node_id" class="Node" 
/> 

<many-to-many column="Cconnection_id" class="Connection"/> 
</map> 


第 二 种 方法 是 简单 的 把 关联 重新 建 模 为 一 个 实体 类 。 这 使 我 们 最 经 常 使 用 的 方法 。 
最 后 一 种 选择 是 使 用 复合 元 素 ， 我 们 会 在 后 面 讨 论 


6.3.5， 使 用 &]t;idbag&gt; 


如 果 你 完全 信奉 我 们 对 于 “联合 主键 (composite keys) HAHA" > Fo KAGE 
使 用 (无 机 的 ) 自己 生成 的 代用 标识 符 (surrogate keys) "的 观点 ， 也 许 你 会 感到 
有 一 些 奇 怪 ， 我 们 目前 为 止 展示 的 多 对 多 关联 和 值 集合 都 是 映射 成 为 带 有 联合 主键 
的 表 的 ! 现在 ， 这 一 点 非常 值得 争辩 ; 看 上 去 一 个 单纯 的 关联 表 并 不 能 从 代用 标识 
符 中 获得 什么 好 处 (虽然 使 用 组 合 值 的 集合 可 能 会 获得 一 点 好 处 ) 。 不 过 ， 
Hibernate 提 供 了 一 个 (一 点 点 试验 性 质 的 ) 功能 ， 让 你 把 多 对 多 关联 和 值 集 合 应 得 
到 一 个 使 用 代用 标识 符 的 表 去 。 


&lt;idbag&gt; 属性 让 你 使 用 bag 语 义 来 映射 一 个 List (或 Collection )。 


<idbag name="lovers" table="LOVERS"> 
<collection-id column="ID" type="long"> 
<generator class="sSequence"/> 
</collection-id> 
<key column="PERSON1"/> 
<many-to-many column="PERSON2" class="Person" fetch="join"/> 
</idbag> 


你 可 以 理解 ， &lt;idbag&gt; 人 工 的 id 生成 器 ， 就 好 像 是 实体 类 一 样 | 集合 的 每 
一 行 都 有 一 个 不 同 的 人 造 关 键 字 。 但 是 ，Hibernate 没 有 提供 任何 机 制 来 让 你 取得 某 
个 特定 行 的 人 造 关 键 字 。 


注意 &lt;idbag&gt; 的 更 新 性 能 要 比 普通 的 alt;bagagt; 高 得 多 ! Hibernate 可 
以 有 效 的 定位 到 不 同 的 行 ， 分 别 进行 更 新 或 删除 工作 ， 就 如 同 处 理 一 个 list, map 或 
者 set 一 样 。 


在 目前 的 实现 中 ， 还 不 支持 使 用 identity 标识 符 生成 器 策略 来 生 
成 &lt;idbag&gt; 集合 的 标识 符 。 


6.4. 集合 例子 (Collection example) 
在 前 面 的 几 个 章节 的 确 非常 令 人 迷 患 。 因 此 让 我 们 来 看 一 个 例子 。 这 个 类 : 


package eg; 
import java.util.Set; 


public class Parent { 
private long id; 
private Set children; 


public long getId() { return id; } 
private void setId(long id) { this.id=id; } 


private Set getChildren() { return children; } 
private void setChildren(Set children) { this.children=child 
ren; } 


这 个 类 有 一 个 Child 的 实例 集合 。 如 果 每 一 个 子 实例 至 多 有 一 个 父 实 例 , PARA 
然 的 映射 是 一 个 one-to-many 的 关联 关系 : 


<hibernate-mapping> 


<class name="Parent"> 
<id name="id"> 
<generator class="sequence"/> 
</id> 
<set name="children"> 
<key column="parent_id"/> 
<one-to-many class="Child"/> 
</set> 
</class> 


<class name="Child"> 
<id name="id"> 
<generator class="Ssequence"/> 
</id> 
<property name="name"/> 
</class> 


</hibernate-mapping> 


在 以 下 的 表 定 义 中 反应 了 这 个 映射 关系 : 


create table parent ( id bigint not null primary key ) 

create table child ( id bigint not null primary key, name varcha 
r(255), parent_id bigint ) 

alter table child add constraint childfkO (parent_id) references 
parent 


如 果 父 亲 是 必须 的 , 那么 就 可 以 使 用 双向 one-to-many 的 关联 了 : 


<hibernate-mapping> 


<class name="Parent"> 
<id name="id"> 
<generator class="Sequence"/> 
</id> 
<set name="Children" inverse="true"> 
<key column="parent_id"/> 
<one-to-many class="Child"/> 
</set> 
</class> 


<class name="Child"> 
<id name="id"> 
<generator class="sequence"/> 
</id> 
<property name="name"/> 
<many-to-one name="parent" class="Parent" column="parent 
_id" not-null="true"/> 
</class> 


</hibernate-mapping> 


请 注意 NOT NULL MAR: 


create table parent ( id bigint not null primary key ) 
create table child ( id bigint not null 
primary key, 
name varchar(255), 
parent_id bigint not null ) 
alter table child add constraint childfkO (parent_id) references 
parent 


另外 ， 如 果 你 绝对 坚持 这 个 关联 应 该 是 单 向 的 ， 你 可 以 对 &1lt;key&gt; RAF 
明 NOT NULL 约束 : 


<hibernate-mapping> 


<class name="Parent"> 
<id name="id"> 
<generator class="Ssequence"/> 
</id> 
<set name="children"> 
<key column="parent_id" not-null="true"/> 
<one-to-many class="Child"/> 
</set> 
</class> 


<class name="Child"> 
<id name="id"> 
<generator class="sequence"/> 
</id> 
<property name="name"/> 
</class> 


</hibernate-mapping> 


另外 一 方面 ,如 果 一 个 子 实例 可 能 有 多 个 父 实例 , 那么 就 应 该 使 用 many-to-many 关 
联 : 


<hibernate-mapping> 


<class name="Parent"> 
<id name="id"> 
<generator class="sequence"/> 
</id> 
<set name="children" table="childset"> 
<key column="parent_id"/> 
<many-to-many class="Child" column="child_id"/> 
</set> 
</class> 


<class name="Child"> 
<id name="id"> 
<generator class="sSequence"/> 
</id> 
<property name="name"/> 
</class> 


</hibernate-mapping> 


REL: 


create table parent ( id bigint not null primary key ) 
create table child ( id bigint not null primary key, name varcha 
r(255) ) 
create table childset ( parent_id bigint not null, 

child_id bigint not null, 

primary key ( parent_id, child_id ) ) 
alter table childset add constraint childsetfkO (parent_id) refe 
rences parent 
alter table childset add constraint childsetfki (child_id) refer 
ences child 


更 多 的 例子 ,以 及 一 个 完整 的 父 / 子 关系 映射 的 排练 ,请 参阅 第 21 章 示例 : 父子 关系 
(Parent Child Relationships). 


甚至 可 能 出 现 更 加 复杂 的 关联 映射 ,我 们 会 在 下 一 章 中 列 出 所 有 可 能 性 。 


第 7 章 关 联 关 系 映射 
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. 单 向 关联 (Unidirectional associations ) 


7.2.1. 多 对 一 (many to one) 
7.2.2. 一 对 一 (one to one ) 
7.2.3. 一 对 多 (one to many) 


. 使 用 连接 表 的 单 向 关联 (Unidirectional associations with join tables ) 


7.3.1. 一 对 多 (one to many) 

7.3.2. 多 对 一 (many to one) 

7.3.3. 一 对 一 (one to one) 

7.3.4. 多 对 多 (many to many) 

双向 关联 (Bidirectional associations ) 

7.4.1. 一 对 多 (one to many) / 多 对 一 (many to one) 
7.4.2. 一 对 一 (one to one) 

使 用 连接 表 的 双向 关联 (Bidirectional associations with join tables ) 
7.5.1. 一 对 多 (one to many) /多 对 一 ( many to one) 
7.5.2. 一 对 一 (one to one) 

7.5.3. 多 对 多 (many to many) 


.更 复杂 的 关联 映射 


7.1. 介绍 


关联 关系 映射 通常 情况 是 最 难 配 置 正 确 的 。 在 这 个 部 分 中 ， 我 们 从 单 向 关系 映射 开 
始 ， 然 后 考虑 双向 关系 映射 ， 由 浅 至 深 讲 述 一 遍 典 型 的 案例 。 在 所 有 的 例子 中 ， 我 
们 都 使 用 person 和 Address 。 


我 们 根据 映射 关系 是 否 涉及 连接 表 以 及 多 样 性 来 划分 关联 类 型 。 


在 传统 的 数据 建 模 中 ， 允 许 为 Null 值 的 外 键 被 认为 是 一 种 不 好 的 实践 ， 因 此 我 们 所 
有 的 例子 中 都 使 用 不 允许 为 Null 的 外 键 。 这 并 不 是 Hibernate 的 要 求 ， 即 使 你 删除 掉 
不 允许 为 Null 的 约束 ，Hibernate 映 射 一 样 可 以 工作 的 很 好 。 


7.2. 单 向 关联 (Unidirectional associations ) 


7.2.1. 乡 对 一 (many to one) 
单 向 many-to-one 关 联 是 最 常见 的 单 向 关联 关系 。 


<class name="Person"> 
<id name="id" column="personId"> 
<generator class="native"/> 
</id> 
<many-to-one name="address" 
column="addressId" 
not -null="true"/> 
</class> 


<class name="Address"> 
<id name="id" column="addressId"> 
<generator class="native"/> 
</id> 
</class> 


create table Person ( personId bigint not null primary key, addr 
essId bigint not null ) 
create table Address ( addressId bigint not null primary key ) 


7.2.2. 一 对 一 (one to one ) 


基于 外 键 关联 的 单 向 一 对 一 关联 和 单 向 多 对 一 关联 几乎 是 一 样 的 。 唯 一 的 不 同 就 是 
单 向 一 对 一 关联 中 的 外 键 字段 具有 唯一 性 约束 。 


<class name="Person"> 
<id name="id" column="personId"> 
<generator class="native"/> 
</id> 
<many-to-one name="address" 
column="addressId" 
unique="true" 
not -null="true"/> 
</class> 


<class name="Address"> 
<id name="id" column="addressId"> 
<generator class="native"/> 
</id> 
</class> 


create table Person ( personId bigint not null primary key, addr 
essId bigint not null unique ) 
create table Address ( addressId bigint not null primary key ) 


基于 主键 关联 的 单 向 一 对 一 关联 通常 使 用 一 个 特定 的 id 生成 器 。 (请 注意 ， 在 这 个 
例子 中 我 们 掉 换 了 关联 的 方向 。) 


<class name="Person"> 
<id name="id" column="personId"> 
<generator class="native"/> 
</id> 
</class> 


<class name="Address"> 
<id name="id" column="personId"> 
<generator class="foreign"> 
<param name="property">person</param> 
</generator> 
</id> 
<one-to-one name="person" constrained="true"/> 
</class> 


create table Person ( personId bigint not null primary key ) 
create table Address ( personId bigint not null primary key ) 


7.2.3. —3} 2 (one to many) 
基于 外 键 关联 的 单 向 一 对 多 关联 是 一 种 很 少见 的 情况 ， 并 不 推荐 使 用 。 


<class name="Person"> 
<id name="id" column="personId"> 
<generator class="native"/> 
</id> 
<set name="addresses"> 
<key column="personId" 
not -null="true"/> 
<one-to-many class="Address"/> 
</set> 
</class> 


<class name="Address"> 
<id name="id" column="addressId"> 
<generator class="native"/> 
</id> 
</class> 


create table Person ( personId bigint not null primary key ) 
create table Address ( addressId bigint not null primary key, pe 
rsonId bigint not null ) 


我 们 认为 对 于 这 种 关联 关系 最 好 使 用 连接 表 。 


7.3. 使 用 连接 表 的 单 向 关联 (Unidirectional 
associations with join tables ) 


7.3.1. 一 对 乡 (one to many) 


基于 连接 表 的 单 向 一 对 多 关联 应 该 优先 被 采用 。 请 注意 ， 通 过 指 
定 unique="true" ， 我 们 可 以 把 多 样 性 从 多 对 多 改变 为 一 对 多 。 


<class name="Person"> 
<id name="id" column="personId"> 
<generator class="native"/> 
</id> 
<set name="addresses" table="PersonAddress"> 
<key column="personId"/> 
<many-to-many column="addressId" 
unique="true" 
class="Address"/> 
</set> 
</class> 


<class name="Address"> 
<id name="id" column="addressId"> 
<generator class="native"/> 
</id> 
</class> 


create table Person ( personId bigint not null primary key ) 

create table PersonAddress ( personId not null, addressId bigint 
not null primary key ) 

create table Address ( addressId bigint not null primary key ) 


7.3.2. 乡 对 一 (many to one) 
基于 连接 表 的 单 向 多 对 一 关联 在 关联 关系 可 选 的 情况 下 应 用 也 很 普遍 。 


<class name="Person"> 
<id name="id" column="personId"> 
<generator class="native"/> 
</id> 
<join table="PersonAddress" 
optional="true"> 
<key column="personId" unique="true"/> 
<many-to-one name="address" 
column="addressId" 
not -null="true"/> 
</join> 
</class> 


<class name="Address"> 
<id name="id" column="addressId"> 
<generator class="native"/> 
</id> 
</class> 


create table Person ( personId bigint not null primary key ) 
create table PersonAddress ( personId bigint not null primary ke 
y, addressId bigint not null ) 

create table Address ( addressId bigint not null primary key ) 


7.3.3. 一 对 一 (one to one ) 
基于 连接 表 的 单 向 一 对 一 关联 非常 少见 ， 但 也 是 可 行 的 。 


<class name="Person"> 
<id name="id" column="personId"> 
<generator class="native"/> 
</id> 
<join table="PersonAddress" 
optional="true"> 
<key column="personId" 
unique="true"/> 
<many-to-one name="address" 
column="addressId" 
not -null="true" 
unique="true"/> 
</join> 
</class> 


<class name="Address"> 
<id name="id" column="addressId"> 
<generator class="native"/> 
</id> 
</class> 


create table Person ( personId bigint not null primary key ) 
create table PersonAddress ( personId bigint not null primary ke 
y, addressId bigint not null unique ) 

create table Address ( addressId bigint not null primary key ) 
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.3.4. 3% % (many to many) 
后 ， 还 有 单 向 多 对 多 关联 


<class name="Person"> 
<id name="id" column="personId"> 
<generator class="native"/> 
</id> 
<set name="addresses" table="PersonAddress"> 
<key column="personId"/> 
<many-to-many column="addressId" 
class="Address"/> 
</set> 
</class> 


<class name="Address"> 
<id name="id" column="addressId"> 
<generator class="native"/> 
</id> 
</class> 


create table Person ( personId bigint not null primary key ) 

create table PersonAddress ( personId bigint not null, addressId 
bigint not null, primary key (personId, addressId) ) 

create table Address ( addressId bigint not null primary key ) 


7.4. 双向 关联 (Bidirectional associations ) 


7.4.1. 一 对 多 (one to many) / 乡 对 一 (many to 
one ) 


双向 多 对 一 关联 是 最 常见 的 关联 关系 。 (这 也 是 标准 的 父 / 子 关联 关系 。 ) 


<class name="Person"> 
<id name="id" column="personId"> 
<generator class="native"/> 
</id> 
<many-to-one name="address" 
column="addressId" 
not -null="true"/> 
</class> 


<class name="Address"> 
<id name="id" column="addressId"> 
<generator class="native"/> 
</id> 
<set name="people" inverse="true"> 
<key column="addressId"/> 
<one-to-many class="Person"/> 
</set> 
</class> 


create table Person ( personId bigint not null primary key, addr 
essId bigint not null ) 
create table Address ( addressId bigint not null primary key ) 


如 果 你 使 用 List (或 者 其 他 有 序 集合 类 )， 你 需要 设置 外 键 对 应 的 key 列 为 
not null ,让 Hibernate 来 从 集合 端 管理 关联 ， 维 护 每 个 元 素 的 索引 (通过 设 
置 update="false" and insert="false" 来 对 另 一 端 反 向 操作 ) © 


<class name="Person"> 
<id name="id"/> 


<many-to-one name="address" 
column="addressId" 
not -null="true" 
insert="false" 
update="false"/> 
</class> 


<class name="Address"> 
<id name="id"/> 


<list name="people"> 
<key column="addressId" not-null="true"/> 
<list-index column="peopleIdx"/> 
<one-to-many class="Person"/> 
</list> 
</class> 


假若 集合 映射 的 &lt;key&gt; 元 素 对 应 的 底层 外 键 字段 是 NOT NULL HY? PAA 
这 一 key 元 素 定 义 not-null="true" 是 很 重要 的 。 不 要 仅仅 为 可 能 的 秦 

Æ @lt;columnaégt; 元 素 定 义 not-null="true" > &lt;key&gt; 元 素 也 是 需 
要 的 。 


7.4.2. 一 对 一 (one to one) 
基于 外 键 关联 的 双向 一 对 一 关联 也 很 常见 。 


<class name="Person"> 
<id name="id" column="personId"> 
<generator class="native"/> 
</id> 
<many-to-one name="address" 
column="addressId" 
unique="true" 
not -null="true"/> 
</class> 


<class name="Address"> 
<id name="id" column="addressId"> 
<generator class="native"/> 
</id> 
<one-to-one name="person" 
property-ref="address"/> 
</class> 


create table Person ( personId bigint not null primary key, addr 
essId bigint not null unique ) 
create table Address ( addressId bigint not null primary key ) 


基于 主键 关联 的 一 对 一 关联 需要 使 用 特定 的 id 生成 器 。 


<class name="Person"> 
<id name="id" column="personId"> 
<generator class="native"/> 
</id> 
<one-to-one name="address"/> 
</class> 


<class name="Address"> 
<id name="id" column="personId"> 
<generator class="foreign"> 
<param name="property">person</param> 
</generator> 
</id> 
<one-to-one name="person" 
constrained="true"/> 
</class> 


create table Person ( personId bigint not null primary key ) 
create table Address ( personId bigint not null primary key ) 


7.5. 使 用 连接 表 的 双向 关联 ( Bidirectional 
associations with join tables ) 


7.5.1. 一 对 多 (one to many) / 乡 对 一 ( many to 
one ) 


基于 连接 表 的 双向 一 对 多 关联 。 注 意 inverse="true" 可 以 出 现在 关联 的 任意 一 
端 ， 即 collection 端 或 者 join 端 。 


<class name="Person"> 
<id name="id" column="personId"> 
<generator class="native"/> 
</id> 
<set name="addresses" 
table="PersonAddress"> 
<key column="personId"/> 
<many-to-many column="addressId" 
unique="true" 
class="Address"/> 
</set> 
</class> 


<class name="Address"> 
<id name="id" column="addressId"> 
<generator class="native"/> 
</id> 
<join table="PersonAddress" 
inverse="true" 
optional="true"> 
<key column="addressId"/> 
<many-to-one name="person" 
column="personId" 
not -null="true"/> 
</join> 
</class> 


create table Person ( personId bigint not null primary key ) 

create table PersonAddress ( personId bigint not null, addressId 
bigint not null primary key ) 

create table Address ( addressId bigint not null primary key ) 


7.5.2. 一 对 一 (one to one) 
基于 连接 表 的 双向 一 对 一 关联 极为 军 见 ， 但 也 是 可 行 的 。 


<class name="Person"> 
<id name="id" column="personId"> 
<generator class="native"/> 
</id> 
<join table="PersonAddress" 
optional="true"> 
<key column="personId" 
unique="true"/> 
<many-to-one name="address" 
column="addressId" 
not -null="true" 
unique="true"/> 
</join> 
</class> 


<class name="Address"> 
<id name="id" column="addressId"> 
<generator class="native"/> 
</id> 
<join table="PersonAddress" 
optional="true" 
inverse="true"> 
<key column="addressId" 
unique="true"/> 
<many-to-one name="person" 
column="personId" 
not -null="true" 
unique="true"/> 
</join> 
</class> 


create table Person ( personId bigint not null primary key ) 
create table PersonAddress ( personId bigint not null primary ke 
y, addressId bigint not null unique ) 

create table Address ( addressId bigint not null primary key ) 


7.5.3. 多 对 多 (many to many ) 
后 ， 还 有 双向 多 对 多 关联 . 


<class name="Person"> 
<id name="id" column="personId"> 
<generator class="native"/> 
</id> 
<set name="addresses" table="PersonAddress"> 
<key column="personId"/> 
<many-to-many column="addressId" 
class="Address"/> 
</set> 
</class> 


<class name="Address"> 
<id name="id" column="addressId"> 
<generator class="native"/> 
</id> 
<set name="people" inverse="true" table="PersonAddress"> 
<key column="addressId"/> 
<many-to-many column="personId" 
class="Person"/> 
</set> 
</class> 


create table Person ( personId bigint not null primary key ) 

create table PersonAddress ( personId bigint not null, addressId 
bigint not null, primary key (personId, addressId) ) 

create table Address ( addressId bigint not null primary key ) 


7.6. 更 复杂 的 关联 映射 


更 复杂 的 关联 连接 极为 罕见。 通过 在 映射 文档 中 风 入 SQL 片断 ，Hibernate 也 可 以 
处 理 更 为 复杂 的 情况 。 上 比如 ， 假 若 包 含 历史 帐户 数据 的 表 定 义 了 accountNumber , 
effectiveEndDate 和 effectiveStartDate 字段 ， 按 照 下 面 映射 : 


<properties name="currentAccountKey"> 

<property name="accountNumber" type="sString" not-null="true" 
/> 

<property name="CcurrentAccount" type="boolean"> 

<formula>case when effectiveEndDate is null then 1 else 

© end</formula> 

</property> 
</properties> 
<property name="effectiveEndDate" type="date"/> 
<property name="effectiveStateDate" type="date" not-null="true"/ 
> 


那么 我 们 可 以 对 目前 (current) 实 例 ( 其 ef fectiveEndDate 为 nu 由 使 用 这 样 的 关联 
映射 : 


<many-to-one name="currentAccountInfo" 
property-ref="currentAccountKey" 
class="AccountIinfo"> 
<column name="accountNumber"/> 
<formula>'1'</formula> 
</many - to-one> 


更 复杂 的 例子 ,假想 Employee 和 Organization 之 间 的 关联 是 通过 一 
个 Employment 中 间 表 维护 的 ,而 中 间 表 中 填充 了 很 多 历史 座 员 数据 。 AB fe R wy HR 
新 雇主 ”这 个 关联 (最 新 雇主 就 是 startDate 最 后 的 那个 ) 可 以 这 样 映射 : 


<join> 
<key column="employeeId"/> 
<subselect> 
select employeelId, orgId 
from Employments 
group by orgId 
having startDate = max(startDate) 
</subselect> 
<many-to-one name="mostRecentEmployer" 
class="Organization" 
column="orgId"/> 
</join> 


使 用 这 一 功能 时 可 以 充满 创意 ， 但 通常 更 加 实用 的 是 用 HQL 或 条 件 查询 来 处 理 这 些 
情形 。 
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组 件 (Component) 这 个 概念 在 Hibernate 中 几 处 不 同 的 地 方 为 了 不 同 的 目的 被 重复 使 
Fl. 


8.1. 依赖 对 象 (Dependent objects ) 


组 件 (Component) 是 一 个 被 包含 的 对 象 ， 在 持久 化 的 过 程 中 ， 它 被 当 作 值 类 型 ， 而 
并 非 一 个 实体 的 引用 。 在 这 篇 文档 中 ， 组 件 这 一 术语 指 的 是 面向 对 象 的 合成 概念 
(而 并 不 是 系统 构架 层次 上 的 组 件 的 概念 ) 。 举 个 例子 , 你 对 人 (Person) 这 个 概念 可 
以 像 下 面 这 样 来 建 模 : 


public class Person { 
private java.util.Date birthday; 
private Name name; 
private String key; 
public String getKey() { 
return key; 
} 


private void setKey(String key) { 
this.key=key; 
} 


public java.util.Date getBirthday() { 
return birthday; 


public void setBirthday(java.util.Date birthday) { 
this.birthday = birthday; 


public Name getName() { 
return name; 


public void setName(Name name) { 
this.name = name; 


public class Name { 
char initial; 
String first; 
String last; 
public String getFirst() { 
return first; 
} 


void setFirst(String first) { 
this.first = first; 
} 


public String getLast() { 
return last; 
} 


void setLast(String last) { 
this.last = last; 


public char getInitial() { 
return initial; 
} 


void setInitial(char initial) { 
this.initial = initial; 
} 


在 持久 化 的 过 程 中 ， 姓 名 (Name) 可 以 作为 人 (Person) 的 一 个 组 件 。 需 要 注意 的 
是 :你 应 该 为 姓名 的 持久 化 属性 定义 getter 和 setter 方 法 ,但 是 你 不 需要 实现 任何 的 
接口 或 申明 标识 符 字段 。 


以 下 是 这 个 例子 的 Hibernate 映 射 文件 : 
<class name="eg.Person" table="person"> 


<id name="Key" column="pid" type="string"> 
<generator class="uuid"/> 


</id> 
<property name="birthday" type="date"/> 
<component name="Name" class="eg.Name"> <!-- class attribute 


optional --> 
<property name="initial"/> 
<property name="first"/> 
<property name="last"/> 
</component> 
</class> 


人 员 (Person) 表 中 将 包括 pid , birthday , initial , first 和 last 等 字 
段 。 


就 像 所 有 的 值 类 型 一 样 , 组件 不 支持 共享 引用 。 换 旬 话说 ， 两 个 人 可 能 重 名 ， 但 是 
两 个 Person 对 象 应 该 包含 两 个 独立 的 Name 对 象 ， 只 不 过 这 两 个 Name 对 象 具 有 “ 同 
样 " 的 值 。 组 件 的 值 可 以 为 室 ， 其 定义 如 下 。 每 当 Hibernate 重 新 加 载 一 个 包含 组 件 


的 对 象 ,如 果 该 组 件 的 所 有 字段 为 室 ，Hibernate 将 假定 整个 组 件 为 空 。 在 大 多 数 情 
况 下 ,这 样 假 定 应 该 是 没有 问题 的 。 


组 件 的 属性 可 以 是 任意 一 种 Hibernate 类 型 ( 包括 集合 , 多 对 多 关联 ， 以 及 其 它 组 件 
FF) 。 许 套 组 件 不 应 该 被 当 作 一 种 特殊 的 应 用 (Nested components should not 
be considered an exotic usage) ° Hibernate 倾 向 于 支持 细致 的 (fine-grained) 对 象 
模型 。 

&lt;component&gt; 元 素 还 允许 有 &1t;parent&gt; 子 元 素 ， 用 来 表明 
component 类 中 的 一 个 属性 是 指向 包含 它 的 实体 的 引用 。 


<class name="eg.Person" table="person"> 
<id name="Key" column="pid" type="string"> 
<generator class="uuid"/> 
</id> 
<property name="birthday" type="date"> 
<component name="Name" class="eg.Name" unique="true"> 
<parent name="namedPerson"/> <!-- reference back to the 
Person --> 
<property name="initial"/> 
<property name="first"/> 
<property name="last"/> 
</componentégt ; 
</class> 


8.2. 在 集合 中 出 现 的 依赖 对 象 (Collections of 
dependent objects) 


Hibernate 支 持 组 件 的 集合 (例如 : 一 个 元 素 是 姓名 (Name) 这 种 类 型 hia Ayo 你 可 以 
使 用 &1lt;composite-elementagt; 标签 替代 &lt;element&gt; ie 
的 组 件 集合 。 


<set name="someNames" table="Some_names" lazy="true"> 
<key column="id"/&gt; 
<composite-element class="eg.Name"> <!-- class attribute req 
uired --> 
<property name="initial"/> 
<property name="first"/> 
<property name="last"/>; 
</composite-element> 
</set> 


注意 ， 如 果 你 定义 的 Set 包 含 组 合 元 素 (composite-element) ， 正确 地 实 
现 equals() 和 hashcode() 是 非常 重要 的 。 


组 合 元 素 可 以 包含 组 件 ， 但 是 不 能 包含 集合 。 如 果 你 的 组 合 元 素 自 身 包含 组 件 ,你 
必须 使 用 &lt;nested-composite-element&gt; 标签 。 这 是 一 个 相当 特殊 的 案例 
- 在 一 个 组 件 的 集合 里 ， 那 些 组 件 本 身 又 可 以 包含 其 他 的 组 件 。 这 个 时 候 你 就 应 该 
考虑 一 下 使 用 one-to-many 关 联 是 否 会 更 恰当 。 尝试 对 这 个 组 合 元 素 重 新 建 模 为 一 
个 实体 一 但 是 需要 注意 的 是 ， 虽 然 Java 模 型 和 重新 建 模 前 是 一 样 的 ， 关 系 模型 和 持 

久 性 语义 会 有 细微 的 变化 。 


tHE ie ie a E LA ae T e 为 空 的 属 
性 . 当 删 除 对 象 时 ，Hibernate 必 须 使 用 每 一 个 字段 的 值 来 确定 定 一 条 记 R(t 组 合 元 
RAF? 没有 单独 的 关键 字段 )， 如 果 有 为 null 的 字段 ， 这 样 做 就 不 可 能 了 。 你 必须 
作出 一 个 选择 ， 要 么 在 组 合 元 素 中 使 用 不 能 为 空 的 属性 ， 要 么 选择 使 

用 @lt;listagt; , &lt;map&gt; , &lt;bag&gt; 或 者 &lt;idbagagt; 而 不 
是 &lt;set&gt; 。 

组 合 元 素 有 个 特别 的 用 法 是 它 可 以 包含 一 个 &lt;many-to-one&gt; 元 素 。 类 似 这 
样 的 映射 允许 你 将 一 个 many-to-many 关 联 表 映射 为 组 合 元 素 的 集合 。(A mapping 
like this allows you to map extra columns of a many-to-many association table to 
the composite element class.) 接 下 来 的 的 例子 是 从 Order 到 Item 的 一 个 多 对 
多 的 关联 关系 , 关联 属性 是 purchaseDate , price 和 quantity ° 


<class name="eg.Order" .... > 


<set name="purchasedItems" table="purchase_items" lazy="true 
Ws 
<key column="order_id"> 
<composite-element class="eg.Purchase"> 
<property name="purchaseDate"/> 
<property name="price"/> 
<property name="quantity"/> 
<many-to-one name="item" class="eg.Item"/> <!-- clas 
s attribute is optional --> 
</composite-element> 
</set> 
</class> 


当然 ， 当 你 定义 Item 时 ， 你 无 法 引用 这 些 purchase， 因 此 你 无 法 实现 双向 关联 查 
询 。 记 住 组 件 是 值 类 型 ， 并 且 不 允许 共享 引用 。 某 一 个 特定 的 Purchase 可 以 放 
在 Order 的 集合 中 ， 但 它 不 能 同时 被 Item 所 引用 。 


其 实 组 合 元 素 的 这 个 用 法 可 以 扩展 到 三 重 或 多 重 关联 


<class name="eg.Order" .... > 


<set name="purchasedItems" table="purchase_items" lazy="true 
Ws 
<key column="order_id"> 
<composite-element class="eg.OrderLine"> 
<many-to-one name="purchaseDetails" class="eg.Purcha 
se"/> 
<many-to-one name="item" class="eg.Item"/> 
</composite-element> 
</set> 
</class> 


在 查询 中 ， 表 达 组 合 元 素 的 语法 和 关联 到 其 他 实体 的 语法 是 一 样 的 。 


8.3. 组 件 作 为 Map 的 索引 〈 Components as Map 
indices ) 


&lt;composite-map-key&gt; 元 素 允 许 你 映射 一 个 组 件 类 作为 一 个 Map 的 
key， 前 提 是 你 必须 正确 的 在 这 个 类 中 重 写 了 hashCode() 和 equals() 方法 。 


. 组 件 作为 联合 标识 符 (Components as 
identifiers) 


你 可 以 使 用 一 个 组 件 作 为 一 个 实体 类 的 标识 符 。 你 的 组 件 类 必须 满足 以 下 要 求 : 
e 它 必 须 实现 java.io.Serializable 接口 


e 它 必 须 重 新 实现 equals() 和 hashCode() 方法 , 始终 和 组 合 关键 字 在 数据 库 
中 的 概念 保持 一 臻 


注意 : 在 Hibernate3 中 ， 第 二 个 要 求 并 非 是 Hibernate 强 制 必须 的 。 但 最 好 这 样 做 。 


你 不 能 使 用 一 个 IdentifierGenerator 产生 组 合 关 键 字 。 一 个 应 用 程序 必须 分 配 
A ebb iit 


使 用 &lt;composite-id&gt; 标签 (并 且 内 页 &lt;key-property&a&gt; 元 素 ) 代 
替 通 常 的 &lt;id&gt; 标签 。 比 如 ,，0rderLine LRA 一 个 主键 ， 这 个 主键 依赖 
于 order 的 (联合 ) 主 键 。 


<class name="OrderLine"> 


<composite-id name="id" class="OrderLineId"> 
<key-property name="lineId"/> 
<key-property name="orderId"/> 
<key-property name="customerId"/> 
</composite-id> 


<property name="name"/> 


<many-to-one name="order" class="Order" 
insert="false" update="false"> 
<column name="orderId"/> 
<column name="customerId"/> 
</many - to-one> 


</class> 


现在 ， 任 何 指向 OrderLine 的 外 键 都 是 复合 的 。 在 你 Ne ， 必 须 为 其 他 
类 也 这 样 声 明 。 例 如 ， 一 个 指向 OrderLine 的 关联 可 能 被 这 样 映 射 : 


<many-to-one name="orderLine" class="OrderLine"> 
<!-- the "class" attribute is optional, as usual --> 
<column name="lineId"/> 
<column name="orderId"/> 
<column name="customerId"/> 
</many - to-one> 


(注意 在 各 个 地 方 &lt;column&gt; 标签 都 是 column 属性 的 替代 写法 。 


指向 OrderLine 的 多 对 多 关联 也 使 用 联合 外 键 : 


<set name="undeliveredOrderLines"> 
<key column name="warehouseld"/> 
<many-to-many class="OrderLine"> 
<column name="lineId"/> 
<column name="orderiId"/> 
<column name="customerId"/> 
</many -to-many> 
</set> 


在 Order ¥, OrderLine 的 集合 则 是 这 样 : 


<set name="orderLines" inverse="true"> 
<key> 
<column name="orderId"/> 
<column name="CcustomerId"/> 
</key> 
<one-to-many class="OrderLine"/> 
</set> 


(与 通常 一 样 ，&lt;one-to-many&gt; 元 素 不 声明 任何 列 .) 
假若 OrderLine 本 身 拥 有 一 个 集合 , 它 也 具有 组 合 外 键 。 


) 


<class name="OrderLine"> 


<list name="deliveryAttempts"> 
<key> <!-- a collection inherits the composite key typ 
e --> 
<column name="lineId"/> 
<column name="orderId"/> 
<column name="customerId"/> 
</key> 
<list-index column="attemptId" base="1"/> 
<composite-element class="DeliveryAttempt"> 


</composite-element> 
</set> 
</class> 


8.5. 动态 组 件 (Dynamic components ) 
你 甚至 可 以 映射 Map 类 型 的 属性 : 


<dynamic-component name="userAttributes"> 
<property name="foo" column="FOO" type="string"/> 
<property name="bar" column="BAR" type="integer"/> 
<many-to-one name="baz" class="Baz" column="BAZ_ID"/> 
</dynamic -component> 


从 &1lt;dynamic-componentégt; 了 映射 的 语义 上 来 讲 ， 它 

和 &lt;componentagt; 是 相同 的 。 这 种 映射 类 型 的 优点 在 于 通过 修改 映射 文 

件 ， 就 可 以 具有 在 部 署 时 检测 丨 实 属 性 的 能 力 。 利 用 一 个 DOM 解 析 器 ， 也 可 以 在 程 
序 运行 时 操作 映射 文件 。 更 好 的 是 ， 你 可 以 通过 Configuration 对 象 来 访问 (或 
者 修改 ) Hibernate 的 运行 时 元 模型 。 


第 9 章 继承 映射 (Inheritance Mappings) 
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a 
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每 个 类 分 层 结构 一 张 表 (Table per class hierarchy) 

. 每 个 子 类 一 张 表 (Table per subclass) 

. 每 个 子 类 一 张 表 (Table per subclass)， 使 用 辨别 标志 (Discriminatonm) 
. 混合 使 用 "每 个 类 分 层 结构 一 张 表 " 和 "每 个 子 类 一 张 表 ” 

每 个 具体 类 一 张 表 (Table per concrete class) 

Table per concrete class, using implicit polymorphism 

. 隐 式 多 态 和 其 他 继承 映射 混合 使 用 
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9.1. 三 种 策略 


Hibernate 支 持 三 种 基本 的 继承 映射 策略 : 
© 每 个 类 分 层 结构 一 张 表 (table per class hierarchy) 
。 每 个 子 类 一 张 表 (table per subclass) 
e 每 个 具体 类 一 张 表 (table per concrete class) 
此 外 ，Hibernate 还 支持 第 四 种 稍 有 不 同 的 多 态 映 射 策略 : 
e 隐 式 多 态 (implicit polymorphism) 


对 于 同一 个 继承 层次 内 的 不 同 分 支 ， 可 以 采用 不 同 的 映射 策略 ， 然 后 用 隐 式 多 AR 
完成 跨越 整个 层次 的 多 态 。 但 是 在 同一 个 &lt;class&gt; 根 元 素 下 ，Hibernate 
不 支持 混合 了 元 素 &lt;subclass&gt; ` 

&lt;joined-subclass&gt; 和 &lt;union-subclass&gt; 的 映射 。 在 同一 

个 &lt;class&gt; 元 素 下 ， 可 以 混合 使 用 “每 个 类 分 层 结构 一 张 表 ”(table per 
hierarchy) 和 "每 个 子 类 一 张 表 ”(table per subclass) 这 两 种 映射 策略 ， 这 是 通过 
结合 元 素 &lt;subclass&gt; 和 &lt;join&gt， 来 实现 的 〈 见 后 ) ° 


在 多 个 映射 文件 中 ， 可 以 直接 在 hibernate-mapping 根 下 定 

SL subclass ， union-subclass 和 joined-subclass 。 也 就 是 说 ， 你 可 以 仅 
加 入 一 个 新 的 映射 文件 来 扩展 类 层次 。 你 必须 在 subclass 的 映射 中 指 

明 extends 属性 ， 给 出 一 个 之 前 定义 的 超 类 的 名 字 。 注 意 ， 在 以 前 ， 这 一 功能 对 
映射 文件 的 顺序 有 严格 的 要 求 ， 从 Hibernate 3 开始 ， 使 用 extends 关 键 字 的 时 候 ， 
对 映射 文件 的 顺序 不 再 有 要 求 ; 但 在 每 个 映射 文件 里 ， 超 类 必须 在 子 类 之 前 定义 。 


<hibernate-mapping> 
<subclass name="DomesticCat" extends="Cat" discriminator-va 
lue="D"> 
<property name="name" type="string"/> 
</subclass> 
</hibernate-mapping> 


9.1.1. 每 个 类 分 层 结构 一 张 表 (Table per class 
hierarchy) 


假设 我 们 有 接口 Payment 和 它 的 几 个 实现 类 : CreditCardPayment , 


CashPayment ,和 ChequePayment 。 则 “每 个 类 分 层 结 构 一 张 表 "(Table per class 
hierarchy) 的 映射 代码 如 下 所 示 : 


<class name="Payment" table="PAYMENT"> 
<id name="id" type="long" column="PAYMENT_ID"> 
<generator class="native"/> 
</id> 
<discriminator column="PAYMENT_TYPE" type="string"/> 
<property name="amount" column="AMOUNT"/> 


<subclass name="CreditCardPayment" discriminator -value="CRED 
cm ph 
<property name="creditCardType" column="CCTYPE"/> 


</subclass> 
<subclass name="CashPayment" discriminator -value="CASH"> 


</subclass> 
<subclass name="ChequePayment" discriminator -value="CHEQUE"> 


</subclass> 


</class> 


采用 这 种 策略 只 需要 一 张 表 即 可 。 它 有 一 个 很 大 的 限制 : 要 求 那 些 由 子 类 定义 的 字 
段 ， 如 CCTYPE ， 不 能 有 非 空 (NOT NULL) 约束 。 


9.1.2. 每 个 子 类 一 张 表 (Table per subclass) 
对 于 上 例 中 的 几 个 类 而 言 ， 采 用 "每 个 子 类 一 张 表 "的 映射 策略 ， 代 码 如 下 所 示 : 


<class name="Payment" table="PAYMENT"> 
<id name="id" type="long" column="PAYMENT_ID"> 
<generator class="native"/> 
</id> 
<property name="amount" column="AMOUNT"/> 


<joined-subclass name="CreditCardPayment" table="CREDIT_PAYM 
ENT"> 
<key column="PAYMENT_ID"/> 


</joined-subclass> 

<joined-subclass name="CashPayment" table="CASH_PAYMENT"> 
<key column="PAYMENT_ID"/> 
<property name="creditCardType" column="CCTYPE"/> 


</joined-subclass> 
<joined-subclass name="ChequePayment" table="CHEQUE_PAYMENT" 


<key column="PAYMENT_ID"/> 
</joined-subclass> 


</class> 


需要 四 张 表 。 三 个 子 类 表 通 过 主键 关联 到 超 类 表 ( 因 而 关系 模型 实际 上 是 一 对 一 关 
联 )。 


9.1.3. 每 个 子 类 一 张 表 (Table per subclass)， 使 用 
辨别 标志 (Discriminator) 


注意 ， 对 “每 个 子 类 一 张 表 ” 的 映射 策略 ，Hibernate 的 实现 不 需要 辨别 字段 ， 而 其 他 
的 对 象 /关系 映射 工具 使 用 了 一 种 不 同 于 Hibernate 的 实现 方法 ， 该 方法 要 求 在 超 类 
A age ce 
实现 ， 但 从 关系 (数据库) 的 角度 来 看 ， ， 按 理 说 它 更 正确 。 若 你 愿意 使 用 带 有 辨别 
字 段 的 “每 个 子 类 一 张 表 " 的 策略 ， 你 可 以 结合 使 用 NEN e 

与 &lt;joinggt; ， 如 下 所 示 : 


<class name="Payment" table="PAYMENT"> 
<id name="id" type="long" column="PAYMENT_ID"> 
<generator class="native"/> 
</id> 
<discriminator column="PAYMENT_TYPE" type="string"/> 
<property name="amount" column="AMOUNT"/> 


<subclass name="CreditCardPayment" discriminator -value="CRED 
IT"> 
<join table="CREDIT_PAYMENT"> 
<key column="PAYMENT_ID"/> 
<property name="creditCardType" column="CCTYPE"/> 


</join> 
</subclass> 
<subclass name="CashPayment" discriminator -value="CASH"> 
<join table="CASH_PAYMENT"> 
<key column="PAYMENT_ID"/> 


</join> 
</subclass> 
<subclass name="ChequePayment" discriminator -value="CHEQUE"> 
<join table="CHEQUE PAYMENT" fetch="select"> 
<key column="PAYMENT_ID"/> 


</join> 
</subclass> 
</class> 


可 选 的 声明 fetch="select" ， 有 是 用 来 告诉 Hibernate， 在 查询 超 类 时 ， 不 要 使 用 
外 部 连接 (outer join) 来 抓 取 子 类 ChequePayment 的 数据 。 


9.1.4. 混合 使 用 “每 个 类 分 层 结构 一 张 表 ”和 “每 个 子 
类 一 张 表 ” 


你 甚至 可 以 采取 如 下 方法 混和 使 用 “每 个 类 分 层 结 构 一 张 表 "和 “每 个 子 类 一 张 表 " 这 两 
种 策略 : 


<class name="Payment" table="PAYMENT"> 
<id name="id" type="long" column="PAYMENT_ID"> 
<generator class="native"/> 
</id> 
<discriminator column="PAYMENT_TYPE" type="string"/> 
<property name="amount" column="AMOUNT"/> 


<subclass name="CreditCardPayment" discriminator -value="CRED 
IT"> 
<join table="CREDIT_PAYMENT"> 
<property name="creditCardType" column="CCTYPE"/> 


</join> 
</subclass> 
<subclass name="CashPayment" discriminator -value="CASH"> 


</subclass> 
<subclass name="ChequePayment" discriminator -value="CHEQUE"> 


</subclass> 


</class> 


对 上 述 任何 一 种 映射 策略 而 言 ， 指 向 根 类 Payment 的 关联 是 使 
用 &lt;many-to-one&gt; 进行 映射 的 。 


<many-to-one name="payment" column="PAYMENT_ID" class="Payment"/ 
> 


9.1.5. 每 个 具体 类 一 张 表 (Table per concrete 
class) 


对 于 “每 个 具体 类 一 张 表 ” 的 映射 策略 ， 可 以 采用 两 种 方法 。 第 一 种 方法 是 使 用 


&lt;union-subclass&gt; ° 


<class name="Payment"> 
<id name="id" type="long" column="PAYMENT_ID"> 
<generator class="Ssequence"/> 
</id> 
<property name="amount" column="AMOUNT"/> 


<union-subclass name="CreditCardPayment" table="CREDIT_PAYME 
NT"> 
<property name="creditCardType" column="CCTYPE"/> 


</union-subclass> 
<union-subclass name="CashPayment" table="CASH_PAYMENT"> 


</union-subclass> 
<union-subclass name="ChequePayment" table="CHEQUE_PAYMENT"> 


</union-subclass> 
</class> 


这 里 涉及 三 张 与 子 类 相关 的 表 。 每 张 表 为 对 应 类 的 所 有 属性 (包括 从 超 类 继承 的 属 
性 ) 定义 相应 字段 。 


这 种 方式 的 局 限 在 于 ， 如 果 一 个 属性 在 超 类 中 做 了 了 映射， 其 字段 名 必须 与 所 有 子 类 
表 中 定义 的 相同 。( 我 们 可 能 会 在 Hibernate 的 后 续 发 布 版 本 中 放宽 此 限制 。) 不 允许 
在 联合 子 类 (union subclass) 的 继承 层次 中 使 用 标识 生成 器 策略 (identity generator 
strategy), 实际 上 , 主键 的 种 子 (primary key seed) 不 得 不 为 同一 继承 层次 中 的 全 部 被 
联合 子 类 所 共用 . 


假若 超 类 是 抽象 类 ， 请 使 用 abstract="true" 。 当 然 ， 假 若 它 不 是 抽象 的 ， 需 要 
一 个 额外 的 表 (上 面 的 例子 中 ， 默 认 是 PAYMENT ) ， 来 保存 超 类 的 实例 。 


9.1.6. Table per concrete class, using implicit 
polymorphism 


另 一 种 可 供 选择 的 方法 是 采用 隐 式 多 态 : 


<class name="CreditCardPayment" table="CREDIT_PAYMENT"> 
<id name="id" type="long" column="CREDIT_PAYMENT_ID"> 
<generator class="native"/> 
</id> 
<property name="amount" column="CREDIT_AMOUNT"/> 


</class> 
<class name="CashPayment" table="CASH_PAYMENT"> 
<id name="id" type="long" column="CASH_PAYMENT_ID"> 
<generator class="native"/> 


</id> 
<property name="amount" column="CASH_AMOUNT"/> 


</class> 
<class name="ChequePayment" table="CHEQUE_PAYMENT"> 
<id name="id" type="long" column="CHEQUE_PAYMENT_ID"> 
<generator class="native"/> 


</id> 
<property name="amount" column="CHEQUE_AMOUNT"/> 


</class> 


注意 ， 我 们 没有 在 任何 地 方 明确 的 提 及 接口 Payment 。 同 时 注意 Payment 的 属 
性 在 每 个 子 类 中 都 进行 了 映射 。 如 果 你 想 避 免 重复 ， 可 以 考虑 使 用 XML 实体 ( 例 
如 :位 于 DOCTYPE 声明 内 的 

[ @lt;!ENTITY allproperties SYSTEM "allproperties.xml"&gt; ] 和 映射 
中 的 &allproperties; )° 


这 种 方法 的 缺陷 在 于 ， 在 Hibernate 执 行 多 态 查询 时 (polymorphic queries) 无 法 生成 
带 UNION *)SQLi& 4] © 

对 于 这 种 映射 策略 而 言 ， 通 常用 &1t;any&gt; 来 实现 到 Payment 的 多 态 关 联 映 
射 。 


<any name="payment" meta-type="string" id-type="long"> 
<meta-value value="CREDIT" class="CreditCardPayment"/> 
<meta-value value="CASH" class="CashPayment"/> 
<meta-value value="CHEQUE" class="ChequePayment"/> 
<column name="PAYMENT_CLASS"/> 
<column name="PAYMENT_ID"/> 

</any> 


9.1.7. 隐 式 多 态 和 其 他 继承 映射 混合 使 用 


对 这 一 映射 还 有 一 点 需要 注意 。 因 为 每 个 子 类 都 在 各 自 独立 的 元 

素 &@lt;classagt; 中 映射 (并 且 Payment 只 是 一 个 接口 )， 每 个 子 类 可 以 很 容易 
的 成 为 另 一 个 继承 体系 中 的 一 部 分 ! (你 仍然 可 以 对 接口 Payment 使 用 多 态 查 
询 。) 


<class name="CreditCardPayment" table="CREDIT_PAYMENT"> 
<id name="id" type="long" column="CREDIT_PAYMENT_ID"> 
<generator class="native"/> 
</id> 
<discriminator column="CREDIT_CARD" type="string"/> 
<property name="amount" column="CREDIT_AMOUNT"/> 


<subclass name="MasterCardPayment" discriminator -value="MDC" 
/> 

<subclass name="VisaPayment" discriminator -value="VISA"/> 
</class> 


<class name="NonelectronicTransaction" table="NONELECTRONIC_TXN" 
> 
<id name="id" type="long" column="TXN_ID"> 
<generator class="native"/> 
</id> 


<joined-subclass name="CashPayment" table="CASH_PAYMENT"> 
<key column="PAYMENT_ID"/> 
<property name="amount" column="CASH_AMOUNT"/> 


</joined-subclass> 
<joined-subclass name="ChequePayment" table="CHEQUE_PAYMENT" 


> 
<key column="PAYMENT_ID"/> 
<property name="amount" column="CHEQUE_AMOUNT"/> 
</joined-subclass> 
</class> 


我 们 还 是 没有 明确 的 提 到 Payment 。 如 果 我 们 针对 接口 Payment 执行 查询 
如 from Payment 一 一 Hibernate 自动 返回 CreditCardPayment (和 它 的 子 类 ， 
因为 它们 也 实现 了 接口 Payment )、 CashPayment 和 Chequepayment 的 实 
例 ， 但 不 返回 NonelectronicTransaction 的 实例 。 





9.2. 限制 


对 “每 个 具体 类 映射 一 张 表 ”(table per concrete-class) 的 映射 策略 而 言 ， 隐 式 多 态 
的 方式 有 一 定 的 限制 。 而 &1lt;union-subclass&gt; 映射 的 限制 则 没有 那 AP 
格 。 

下 面 表 格 中 列 出 了 在 Hibernte 中 “每 个 具体 类 一 张 表 ”的 策略 和 隐 式 多 态 的 限制 。 


表 9.1. 继承 映射 特性 (Features of inheritance mappings) 


继承 策略 
(Inheritance 多 态 多 对 一 多 态 一 对 一 4 
strategy) 
每 个 类 分 层 
&lt;many-to-one&gt; &lt;one-to-one&gt; &lt;or 
结构 一 张 表 x 3 z 
NS 
a &lt;many-to-one&gt; &lt;one-to-one&gt; &lt;or 
每 个 具体 类 SU 
= oh x 
RR &lt;many-to-oneégt; &lt;one-to-one&gt; (12 i 
(union- 于 inve 
subclass) 情况 ) 
每 个 具体 类 
一 张 表 ( 隐 式 &lt;any&gt; 不 支持 不 支持 
ZA 


3 ®) 
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Hibernate 是 完整 的 对 象 /关系 映射 解决 方案 ， 它 提供 了 对 象 状态 管理 (state 
managemen 了 ) 的 功能 能 ， 使 开发 者 不 再 需要 理会 底层 数据 库 系 统 的 细节 。 也 就 是 
说 ， 相 对 于 常见 的 JDBC/SQL 持 久 层 方案 中 需要 管理 SQL 语句 ，Hibernate 采 用 了 
更 自然 的 面向 对 象 的 视角 来 持久 化 Java 应 用 中 的 数据 。 


换 名 话说， 使 用 Hibernate 的 开发 者 应 该 总 是 关注 对 象 的 状态 (state) > T sk % SQL 
语句 的 执行 。 这 部 分 分 细节 节 已 经 由 Hibernate 掌 管 妥 当 ， 只 有 开发 者 在 进行 系统 性 能 
调 优 的 时 候 才 需要 进行 了 解 。 


10.1. Hibernate *t 4% Æ (object states) 


Hibernate € t # X4¥ F 3] xt RAK A (state): 


e It (Transient) - 由 new 操作 符 创 建 ， 且 尚未 与 Hibernate Session 关联 的 
对 象 被 认定 为 瞬时 (Transient) 的 。 瞬 时 (Transient) 对 象 不 会 被 持久 化 到 数据 库 
中 ， 也 不 会 被 赋予 持久 化 标识 (identifier)。 如 果 明 时 (Transient) 对 象 在 程序 中 
没有 被 引用 ， 它 会 被 垃圾 回收 器 (garbage collector)#4 $t ° 使 用 Hibernate 

Session 可 以 将 其 变 为 持久 (Persistent) 状 态 。(Hibernate 会 自动 执行 必要 的 
SALÈ 47) 


e 44% (Persistent) - 持久 (Persistent) 的 实例 在 数据 库 中 有 对 应 的 记录 ， 并 拥有 一 
个 持久 化 标识 (identifier)。 持久 (Persistent) 的 实例 可 能 是 刚 被 保存 的 ， 或 刚 被 
加 载 的 ， 无 论 哪 一 种 ， 按 定义 ， 它 存在 于 相关 联 的 Session 作用 范围 内 。 
Hibernate 会 检测 到 处 于 持久 (Persistent) 状 态 的 对 象 的 任何 改动 ， 在 当前 操作 
单元 (unit of work) 执 行 完毕 时 将 对 象 数据 (state) 与 数据 库 同 步 (synchronize)。 
开发 者 不 需要 手动 执行 UPDATE 。 将 对 象 从 持久 (Persistent) 状 态 变 成 瞬时 
(Transient) 状 态 同 样 也 不 需要 手动 执行 DELETE 184) © 


。 脱 管 (Detached) -与 持久 (Persistent) 对 象 关联 的 Session 被 关闭 后 ， 对 象 就 
变 为 脱 管 (Detached) 的 。 对 脱 管 (Detached) 对 象 的 引用 依然 有 效 ， 对 象 可 继续 
被 修改 。 脱 管 (Detached) 对 象 如 果 重 新 关联 到 某 个 新 的 Session 上 ， 会 再 次 
转变 为 持久 (Persistent) 的 (在 Detached 其 间 的 改动 将 被 持久 化 到 数据 库 )。 这 个 
功能 使 得 一 种 编程 模型 ， 即 中 间 会 给 用 户 思 考 时 间 (user think-time) 的 长 时 间 运 
行 的 操作 单元 (unit of work) 的 编程 模型 成 为 可 能 。 我 们 称 之 为 应 用 程序 事务 ， 
即 从 用 户 观点 看 是 一 个 操作 单元 (unit of work) ° 


接 下 来 我 们 来 细致 的 讨论 下 状态 (states) 及 状态 间 的 转换 (state transitions) (以 及 触 
发 状态 转换 的 Hibernate 方 法 ) 。 


10.2. 使 对 得 持久 化 


Hibernate 认 为 持久 化 类 (persistent class) #7 & I 1.99 xt Z Æ i4 HY (Transient) ° #& 
们 可 通过 将 瞬时 (Transient) 对 象 与 Session 关 联 而 把 它 变 为 持久 (Persistent) 的 。 


DomesticCat fritz = new DomesticCat(); 
fritz.setColor(Color.GINGER); 
fritz.setSex('M'); 

fritz.setName("Fritz"); 

Long generatediId = (Long) sess.save(fritz); 


如 果 Cat 的 持久 化 标识 (identifier) 是 generated ŽA 4 > ASA Kis 12 (identifier) 
会 自动 在 save() 被 调用 时 产生 并 分 配给 cat 。 如 果 cat 的 持久 化 标识 
(identifier) assigned 类 型 的 ， 或 是 一 个 复合 主键 (Composite key) ， 那 么 该 标识 
(identifien) 应 当 在 调用 save() 之 前 手动 赋予 给 cat 。 你 也 可 以 按照 EJB3 early 
draft 中 定义 的 语义 ， 使 用 persist() 替代 save() ° 


此 外 ， 你 可 以 用 一 个 重 载 版 本 的 save() 方法 。 


DomesticCat pk = new DomesticCat(); 
pk.setColor(Color. TABBY) ; 
pk.setSex('F'); 

pk.setName("PK"); 

pk.setKittens( new HashSet() ); 
pk.addkKitten(fritz); 

sess.save( pk, new Long(1234) ); 


如 果 你 持久 化 的 对 象 有 关联 的 对 象 (associated objects) (例如 上 例 中 

的 kittens 集合 ) 那么 对 这 些 对 象 (译注 : pk 和 kittens) 进行 持久 化 的 顺序 是 任 
意 的 〈 也 就 是 说 可 以 先 对 kittens 进 行 持 久 化 也 可 以 先 对 pk 进行 持久 化 ) ， 除 非 你 在 
外 键 列 上 有 NOT NULL 约束 。 Hibernate 不 会 违反 外 键 约束 ， 但 是 如 果 你 用 错误 的 
顺序 持久 化 对 象 (译注 : 在 pk 持久 化 之 前 持久 化 kitten) » MAT RA 

JR NOT NULL 约束 。 


通常 你 不 会 为 这 些 细节 烦心 ， 因 为 你 很 可 能 会 使 用 Hibernate 的 传播 性 持久 化 
(transitive persistence) 功 能 自动 保存 相关 联 那 些 对 象 。 这 样 连 违反 NOT NULL 的 
束 的 情况 都 不 会 出 现 了 - Hibernate 会 管 好 所 有 的 事情 。 传播 性 持久 化 (transitive 
persistence) 将 在 本 章 稍 后 讨论 。 


10.3. KRITA 


如 果 你 知道 某 个 实例 的 持久 化 标识 (identifier)， 你 就 可 以 使 

用 Session 的 load() 方法 来 获取 它 。 load() 的 另 一 个 参数 是 指定 类 
的 ,class 对象。 本 方法 会 创建 指定 类 的 持久 化 实例 ， 并 从 数据 库 加 载 其 数据 
(state) ° 


Cat fritz = (Cat) sess.load(Cat.class, generatedId); 


// you need to wrap primitive identifiers 

long id = 1234; 

DomesticCat pk = (DomesticCat) sess.load( DomesticCat.class, new 
Long(id) ); 


此 外 , 你 可 以 把 数据 (state) 加 载 到 指定 的 对 象 实 例 上 【〈 履 盖 掉 该 实例 原来 的 数据 ) 。 


Cat cat = new DomesticCat(); 

// load pk's state into cat 
sess.load( cat, new Long(pkId) ); 
Set kittens = cat.getKittens(); 


请 注意 如 果 没 有 匹配 的 数据 库 记 录 ， load() 方法 可 能 抛 出 无 法 恢复 的 异常 
(unrecoverable exception)。 如 果 类 的 映射 使 用 了 代理 (proxy)， load() 方法 会 返 
回 一 个 未 初始 化 的 代理 ， 直 到 你 调用 该 代理 的 某 方法 时 才 会 去 访问 数据 库 。 若 你 希 
望 在 菜 对 象 中 创建 一 个 指向 另 一 个 对 象 的 关联 ， 又 不 想 在 从 数据 库 中 装载 该 对 象 时 
同时 装载 相关 联 的 那个 对 象 ， 那 么 这 种 操作 方式 就 用 得 上 的 了 。 如 果 为 相应 类 映射 
关系 设置 了 batch-size ， 那 么 使 用 这 种 操作 方式 允许 多 个 对 象 被 一 批 装载 〈 
为 返回 的 是 代理 ， 无 需 从 数据 库 中 抓 取 所 有 对 象 的 数据 ) 。 


如 果 你 不 确定 是 否 有 匹配 的 行 存在 ， 应 该 使 用 get() 方法 ， 它 会 立刻 访问 数据 
库 ， 如 果 没 有 对 应 的 记录 ， 会 返回 null。 


Cat cat = (Cat) sess.get(Cat.class, id); 
if (cat==null) { 

cat = new Cat(); 

sess.save(cat, id); 


} 


return cat; 


你 甚至 可 以 选用 某 个 LockMode ， 用 SQL 的 SELECT ... FOR UPDATE 装载 对 
象 。 请 查阅 API 文 档 以 获取 更 多 信息 。 


Cat cat = (Cat) sess.get(Cat.class, id, LockMode.UPGRADE) ; 


注意 ， 任 何 关联 的 对 象 或 者 包含 的 集合 都 不 会 被 以 FOR UPDATE 方式 返回 ， 除 非 
你 指定 了 lock 或 者 all 作为 关联 (association) 的 级 联 风 格 (cascade style) ° 


任何 时 候 都 可 以 使 用 refresh() 方法 强迫 装载 对 象 和 它 的 集合 。 如 果 你 使 用 数据 
库 触 发 器 功能 来 处 理 对 象 的 某 些 属性 ， 这 个 方法 就 很 有 用 了 。 


sess.save(cat); 

sess.flush(); //force the SQL INSERT 

sess.refresh(cat); //re-read the state (after the trigger execut 
es) 


此 处 通常 会 出 现 一 个 重要 问题 : Hibernates MAGEE P RRS LRA? 会 执行 多 少 
条 相应 的 SQL SELECT 语句 ? 这 取决 于 抓 取 策 略 (fetching strategy)， 会 在 第 19.1 
节 “ 抓 取 策 略 (Fetching strategies) "中 解释 。 


10.4. 查询 


如 果 不 知 道 所 要 寻找 的 对 象 的 持久 化 标识 ， 那 么 你 需要 使 用 查询 。Hibernate 支 持 强 
大 且 易 于 使 用 的 面向 对 象 查询 语言 (HQL)。 如 果 和 希望 通过 编程 的 方式 创建 查询 ， 
Hibernate 提 供 了 完善 的 按 条 件 (Query By Criteria, QBC) 以 及 按 样 例 (Query By 
Example, QBE) 进 行 查询 的 功能 。 你 也 可 以 用 原生 SQL(native SQL) 描 述 查询 ， 
Hibernate 额 外 提供 了 将 结果 集 (result set) 转 化 为 对 象 的 支持 。 


10.4.1. 执行 查询 


HQL 和 原生 SQL(native SQL) 查 询 要 通过 为 org.hibernate.Query 的 实例 来 表 
达 。 这 个 接口 提供 了 参数 绑 定 、 结 果 集 处 理 以 及 运行 实际 查询 的 方法 。 你 总 是 可 
以 通过 当前 Session 获取 一 个 Query 对 象 : 


List cats = session.createQuery( 
"from Cat as cat where cat.birthdate < ?") 
.setDate(0, date) 
ells lea ca fa he 


List mothers = session.createQuery( 

"select mother from Cat as cat join cat.mother as mother whe 
re cat.name = ?") 

.setString(0, name) 

maS GO 


List kittens = session.createQuery( 
"from Cat as cat where cat.mother = ?") 
.setEntity(0, pk) 
RLS EG 


Cat mother = (Cat) session.createQuery( 
"select cat.mother from Cat as cat where cat = ?") 
.setEntity(0, izi) 
.uniqueResult(); ]] 


Query motherswithKittens = (Cat) session.createQuery( 

"select mother from Cat as mother left join fetch mother.kit 
tens"); 
Set uniqueMothers = new HashSet(motherswithKittens.list()); 


一 个 查询 通常 在 调用 list() 时 被 执行 ， 执 行 结果 会 完全 装载 进 内 存 中 的 一 个 集合 
(collection)。 查询 返回 的 对 象 处 于 持久 (persistent) 状 态 。 如 果 你 知道 的 查询 只 会 返 
回 一 个 对 象 ， 可 使 用 list() 的 快捷 方式 uniqueResult() 。 注意 ， 使 用 集合 预 
先 抓 取 的 查询 往往 会 返回 多 次 根 对 象 〈 他 们 的 集合 类 都 被 初始 化 了 ) 。 你 可 以 通过 
一 个 集合 来 过 滤 这 些 重复 对 象 。 


10.4.1.1. 迭代 式 获 取 结 果 (lterating results) 


某 些 情况 下 ， 你 可 以 使 用 iterate() 方法 得 到 更 好 的 性 能 。 这 通常 是 你 预期 返回 
的 结果 在 Session， 或 二 级 缓存 (Second-level cache) 中 已 经 存在 时 的 情况 。 WER 
然 ，iterate() 会 比 list() 慢 ， 而 且 可 能 简单 查询 也 需要 进行 多 次 数据 库 访 
问 : iterate() 会 首先 使 用 1 条 语句 得 到 所 有 对 象 的 持久 化 标识 (identifiers)， 再 
根据 持久 化 标识 执行 条 附加 的 Select 语句 实例 化 实际 的 对 象 。 


// fetch ids 
Iterator iter = sess.createQuery("from eg.Qux q order by q.likel 
iness").iterate(); 
while ( iter.hasNext() ) { 
Qux qux = (Qux) iter.next(); // fetch the object 
// something we couldnt express in the query 
if ( qux.calculateComplicatedAlgorithm() ) { 
// delete the current instance 
iter.remove(); 
// dont need to process the rest 
break; 


10.4.1.2. 返回 元 组 (tuples) 的 查询 


(译注 :元 组 (tuples) 指 一 条 结果 行 包含 多 个 对 象 ) Hibernate 查 询 有 时 返回 元 组 
(tuples)， 每 个 元 组 (tuples) 以 数组 的 形 式 返 


Iterator kittensAndMothers = sess.createQuery( 

"select kitten, mother from Cat kitten join kitten.m 
other mother") 

.list() 

.iterator(); 


while ( kittensAndMothers.hasNext() ) { 
Object[] tuple = (Object[]) kittensAndMothers.next(); 
Cat kitten = tuple[0]; 
Cat mother = tuple[1]; 


10.4.1.3. 标量 (Scalar) 结 采 


查询 可 在 select 从 名 中 指定 类 的 属性 ， 其 至 可 以 调用 SQL 统 计 (aggregate) 函 
Ro 属性 或 统计 结果 被 认定 为 "标量 (Scalar)" 的 结果 (而 不 是 持久 (persistent state) 
的 实体 ) 。 


Iterator results = sess.createQuery( 

"select cat.color, min(cat.birthdate), count(cat) from C 
at cat " + 

"group by cat.color") 

.list() 

.iterator(); 


while ( results.hasNext() ) { 
Object[] row = (Object[]) results.next(); 
Color type = (Color) row[0]; 
Date oldest = (Date) row[1]; 
Integer count = (Integer) row[2]; 


10.4.1.4. He AA 


接口 Query 提供 了 对 命名 参数 (named parameters) ` JDBC M49 问号 (?) 参数 
进行 绑 定 的 方法 。 不 同 于 JDBC，Hibernate 对 参数 从 0 开始 计数 。 命名 参数 
(named parameters) 在 查询 字符 串 中 是 形 如 :name 的 标识 符 。 命 名 参数 (named 
parameters) 的 优点 是 : 


。 命 名 参数 (named parameters) 与 其 在 查询 串 中 出 现 的 顺序 无 关 
© 它们 可 在 同一 查询 串 中 多 次 出 现 
© 它们 本 身 是 自我 说 明 的 


//named parameter (preferred) 

Query q = sess.createQuery("from DomesticCat cat where cat.name 
= :name"); 

q.setString("name", "Fritz"); 

Iterator cats = q.iterate(); 


//positional parameter 

Query q = sess.createQuery("from DomesticCat cat where cat.name 
= 2"); 

q.setString(0, "Izi"); 

Iterator cats = q.iterate(); 


//named parameter list 

List names = new ArrayList(); 

names.add("Izi"); 

names.add("Fritz"); 

Query q = sess.createQuery("from DomesticCat cat where cat.name 
in (:namesList)"); 

q.setParameterList("namesList", names); 

List cats = q.list(); 


10.4.1.5. 分 页 


如 果 你 需要 指定 结果 集 的 范围 (希望 返回 的 最 大 行 数 /或 开始 的 行 数 ) ， 应 该 使 
用 Query 接口 提供 的 方法 : 


Query q = sess.createQuery("from DomesticCat cat"); 
q.setFirstResult(20); 
q.setMaxResults(10); 
List cats = q.list(); 


Hibernate 知道 如 何 将 这 个 有 限定 条 件 的 查询 转换 成 你 的 数据 库 的 原生 SQL(native 
SQL) ° 


10.4.1.6. T 2 i M (Scrollable iteration) 


如 果 你 的 JDBC 驱 动 支持 可 滚动 的 ResuleSet ， Query 接口 可 以 使 
用 ScrollableResults ， 人 允许 你 在 查询 结果 中 灵活 游 走 。 


Query q = sess.createQuery("Select cat.name, cat from DomesticCa 
acters En eG? 

"order by cat.name"); 
ScrollableResults cats = q.scroll(); 
te C CSa hk UPSET jist 


// find the first name on each page of an alphabetical list 
of cats by name 
firstNamesOfPages = new ArrayList(); 
do { 
String name = cats.getString(0); 
firstNamesOfPages.add(name) ; 


while ( cats.scroll(PAGE_SIZE) ); 


// Now get the first page of cats 

pageOfCats = new ArrayList(); 

cats.beforeFirst(); 

int i=0; 

while( ( PAGE SIZE > i++ ) && cats.next() ) pageOfCats.add( 
cats.get(1) ); 


cats.close() 


请 注意 ， 使 用 此 功能 需要 保持 数据 库 连 接 (以 及 游标 (cursor)) 处 于 一 直 打 开 状 
Ro 如 果 你 需要 断 开 连 接 使 用 分 页 功能 ， 请 使 
用 setMaxResult() / setFirstResult() 


10.4.1.7. 外 置 命名 查询 (Externalizing named 
queries) 


你 可 以 在 映射 文件 中 定义 命名 查询 (named queries)。 (如 果 你 的 查询 串 中 包含 可 
能 被 解释 为 XML 标记 (markup) 的 字符 ， 别 忘 了 用 CDATA & RACK e) 


<query name="ByNameAndMaximumWeight"><! [CDATA[ 
from eg.DomesticCat as cat 
where cat.name = ? 
and cat.weight > ? 
] ]></query> 


参数 绑 定 及 执行 以 编程 方式 (programatically) 完 成 : 


Query q = sess.getNamedQuery("ByNameAndMaximumWeight" ) ; 
q.setString(0, name); 

q.setInt(1, minWeight); 

List cats = q.list(); 


请 注意 实际 的 程序 代码 与 所 用 的 查询 语言 无 关 ， 你 也 可 在 元 数据 中 定义 原生 
SQL(native SQL) 查 询 ， 或 将 原 有 的 其 他 的 查询 语句 放 在 配置 文件 中 ， 这 样 就 可 以 
让 Hibernate 统 一 管理 ， 达 到 迁移 的 目的 。 


也 请 注意 在 &lt;hibernate-mapping&gt， 元 素 中 声明 的 查询 必须 有 一 个 全 局 唯 
一 的 名 字 , 而 在 &lt;classagt; 元 素 中 声明 的 查询 自动 具有 全 局 名 ,是 通过 类 的 全 
名 加 以 限定 的 。 比 如 eg.Cat.ByNameAndMaximumweight ° 


10.4.2. 过 滤 集 合 


集合 过 滤器 (filter) 是 一 种 用 于 一 个 持久 化 集合 或 者 数组 的 特殊 的 查询 。 查 询 字 符 串 
中 可 以 使 用 "this" 来 引用 集合 中 的 当前 元 素 。 


Collection blackKittens = session.createFilter( 

pk.getkittens(), 

"where this.color = ?") 

.setParameter( Color.BLACK, Hibernate.custom(ColorUserType.c 
lass) ) 

.list() 


); 


返回 的 集合 可 以 被 认为 是 一 个 包 (bag, 无 顺序 可 重复 的 集合 (collection))， 它 是 所 给 
集合 的 副本 。 原来 的 集合 不 会 被 改动 (这 与 “过 滤器 (filter)" 的 隐 含 的 含义 不 符 ， 不 
过 与 我 们 期 待 的 行为 一 致 ) 。 


请 注意 过 滤器 (filter) 并 不 需要 from 子 甸 (当然 需要 的 话 它 们 也 可 以 加 上 ) 。 过 滤 
器 (filter) 不 限定 于 只 能 返回 集合 元 素 本 身 。 


Collection blackkittenMates = session.createFilter ( 
pk.getKittens(), 
"select this.mate where this.color = eg.Color.BLACK.intValue 


.list(); 


即使 无 条 件 的 过 滤器 (filter) 也 是 有 意义 的 。 例 如 ， 用 于 加 载 一 个 大 集合 的 子 集 : 


Collection tenkittens = session.createFilter( 
mother.getKittens(), "") 
.setFirstResult(0).setMaxResults(10) 
SEON 


10.4.3. 条 件 查询 (Criteria queries) 


HQL 极 为 强大 ， 但 是 有 些 人 希望 能 够 动态 的 使 用 一 种 面向 对 象 API 创 建 查询 ， 而 非 
在 他 们 的 Java 代 码 中 内 入 字符 串 。 对 于 那 部 分 人 来 说 ，Hibernate 提 供 了 直观 
的 Criteria 查询 API ° 


Criteria crit = session.createCriteria(Cat.class); 
crit.add( Expression.eq( "color", eg.Color.BLACK ) ); 
crit.setMaxResults(10); 

List cats = crit.list(); 


Criteria 以 及 相关 的 样 例 (Example) API 将 会 再 第 15 章 4% 479 (Criteria 
Queries) 中 详细 讨论 。 


10.4.4. 使 用 原生 SQL 的 查询 


你 可 以 使 用 createSQLQuery() 方法 ， 用 SQL 来 描述 查询 ， 并 由 Hibernate 将 结果 
集 转换 成 对 象 。 请 注意 ， 你 可 以 在 任何 时 候 调 用 session.connection() 来 获得 
并 使 用 JDBC Connection 对 象 。 如果 你 选择 使 用 Hibernate 的 APl, 你 必须 把 SQL 
别名 用 大 括号 包围 起 来 : 


List cats = session.createSQLQuery( 
"SELECT {cat.*} FROM CAT {cat} WHERE ROWNUM<10", 
ucatu, 
Cat.class 

).list(); 


List cats = session.createSQLQuery( 

"SELECT {cat}.ID AS {cat.id}, {cat}.SEX AS {cat.sex}, " + 

"{cat}.MATE AS {cat.mate}, {cat}.SUBCLASS AS {cat.cla 

ss}, cay ES 

"FROM CAT {cat} WHERE ROWNUM<10", 

teak, 

Cat.class 
).list() 


和 Hibernate 查 询 一 样 ，SQL 查 询 也 可 以 包含 命名 参数 和 占 位 参数 。 可 以 在 第 16 章 
Native SQL 查 询 找 到 更 多 关于 Hibernate 中 原生 SQL(native SQL) 的 信息 。 


10.5. F RAF AM R 


事务 中 的 持久 实例 (就 是 通过 session 装载 、 保 存 、 创 建 或 者 查询 出 的 对 象 ) 被 
应 用 程序 操作 所 造成 的 任何 修改 都 会 在 Session PR HH (flushed) 的 时 候 被 持久 
化 (本 章 后 面 会 详细 讨论 ) 。 这 里 不 需要 调用 某 个 特定 的 方法 ( 比 

如 update() ， 设 计 它 的 目的 是 不 同 的 ) 将 你 的 修改 持久 化 。 所 以 最 直接 的 更 新 
一 个 对 象 的 方法 就 是 在 Session 处 于 打开 状态 时 load() 它 ， 然 后 直接 修改 即 
可 : 


DomesticCat cat = (DomesticCat) sess.load( Cat.class, new Long(6 


9) ); 

cat.setName("PK"); 

sess.flush(); // changes to cat are automatically detected and 
persisted 


有 时 这 种 程序 模型 效率 低下 ， 因 为 它 在 同一 Session 里 需要 一 条 SQL SELECT 语句 
(用 于 加 载 对 象 ) 以 及 一 条 SQL UPDATE 语句 (持久 化 更 新 的 状态 )。 为 此 
Hibernate 提 供 了 另 一 种 途径 ， 使 用 脱 管 (detached) 实 例 。 


请 注意 Hibernate 本 身 不 提供 直接 执行 UPDATE 或 DELETE 语句 的 API。 Hibernate 
提供 的 是 ”状态 管理 (state management) 服 务 ， 你 不 必 考 虑 要 使 用 的 语句 
(statements) ° JDBC 是 出 色 的 执行 SQL 语 句 的 APl， 任 何 时 候 调 

用 session.connection() 你 都 可 以 得 到 一 个 JDBC Connection 对 象 。 此 外 ， 
在 联机 事务 处 理 (OLTP) 程 序 中 ， 大 量 操作 (mass operations) 与 对 象 /关系 映射 的 观 
点 是 相 冲 突 的 。Hibernate 的 将 来 版 本 可 能 会 提供 专门 的 进行 大 量 操作 (mass 
operation) 的 功能 。 参 考 第 13 章 批量 处 理 (Batch processing) ， 寻 找 一 些 可 用 的 
批量 (batch) 操 作 技巧 。 


10.6. 修改 脱 管 (Detached) 对 象 


很 多 程序 需要 在 某 个 事务 中 获取 对 象 ， 然 后 后 将 对 象 发 送 到 界面 层 去 操作 ， 最 后 在 一 
a 在 高 并 发 访问 的 环境 中 使 用 这 种 方式 ， 通 常 使 用 附带 
版 本 信息 的 数据 来 保证 这 些 “ 长 “工作 单元 之 间 的 隔离 。 


Hibernate 通 过 提供 Session.update() 或 Session.merge() 重新 关联 脱 管 实例 
的 办 法 来 支持 这 种 模型 。 


// in the first session 

Cat cat = (Cat) firstSession.load(Cat.class, catId); 
Cat potentialMate = new Cat(); 
firstSession.save(potentialMate) ; 


// in a higher layer of the application 
cat.setMate(potentialMate) ; 


// later, in a new session 


secondSession.update(cat); // update cat 
secondSession.update(mate); // update mate 


如 果 具 有 catId 持久 化 标识 的 Cat 之 前 已 经 


被 另 一 Session(secondSession) 装载 了 ， 应 用 程序 进行 重 关联 操作 (reattach) 的 
时 候 会 抛 出 一 个 异常 。 
如 果 你 确定 当前 session 没 有 包 具有 相同 持久 化 标识 的 持久 实例 ， 使 


用 update() ° 如 果 想 ， 使 
用 merge() 。 换 和 句 话说 ， 在 一 个 新 session 中 通常 第 一 个 调用 的 是 update() 方 
法 ， 以 便 保证 重新 关联 脱 管 (detached) 对 象 的 操作 首先 被 执行 。 


如 果 项 望 相关 联 的 脱 管 对 象 (通过 引用 “可 到 达 " 的 脱 管 对 象 ) 的 数据 也 要 更 新 到 数 
据 库 时 (并 且 也 仅仅 在 这 种 情况 ) ， 可 以 对 该 相关 联 的 脱 管 对 象 单 独 调 

用 update() 当然 这 些 可 以 自动 完成 ， 即 通过 使 用 传播 性 持久 化 (transitive 
persistence)， 请 看 第 10.11 节 “ 传 播 性 持久 化 (transitive persistence)”。 


lock() 方法 也 允许 程序 重新 关联 某 个 对 象 到 一 个 新 session 上 。 不 过 ， 该 脱 管 
(detached) 的 对 象 必 须 是 没有 修改 过 的 ! 


//just reassociate: 

sess.lock(fritz, LockMode.NONE); 

//do a version check, then reassociate: 

sess.lock(izi, LockMode.READ); 

//do a version check, using SELECT ... FOR UPDATE, then reassoci 
ate: 

sess.lock(pk, LockMode.UPGRADE) ; 


请 注意 ， lock() 可 以 搭配 多 种 LockMode ， 更 多 信息 请 阅读 API 文 档 以 及 关于 
事务 处 理 (transaction handling) 的 草 节 。 重 新 关联 不 是 lock() 的 唯一 用 途 。 


其 他 用 于 长 时 间 工 作 单 元 的 模型 会 在 第 11.3 节 “ 乐 观 并 发 控制 (Optimistic 
concurrency control)” 中 讨论 。 


10.7. 自动 状态 检测 


Hibernate 的 用 户 曾 ee ia 
(transient) 对 象 ， 又 可 更 新 /重新 关联 脱 (detached) 实 例 的 通用 方法 。 
saveOrUpdate() 方法 实现 了 这 个 功能 。 


// in the first session 

Cat cat = (Cat) firstSession.load(Cat.class, catID); 

// in a higher tier of the application 

Cat mate = new Cat(); 

cat.setMate(mate); 

// later, in a new session 

secondSession.saveOrUpdate(cat); // update existing state (cat 
has a non-null id) 


secondSession.saveOrUpdate(mate); // save the new instance (mat 
e has a null id) 


saveOrUpdate() 用 途 和 语义 可 能 会 使 新 用 户 感 到 迷惑 。 首先 ， 只 要 你 没有 党 
在 某 个 session 中 使 用 来 自 另 一 session 的 实例 ， 你 就 应 该 不 需要 使 用 TA, > 
saveOrUpdate() ， 或 merge() 。 有 些 程序 从 来 不 用 这 些 方法 。 


通常 下 面 的 场景 会 使 用 update() 或 saveOrUpdate() 

o 程序 在 第 一 个 session 中 加 载 对 象 

o 该 对 象 被 传递 到 表现 层 

o 对 象 发 生 了 一 些 改动 

o 该 对 象 被 返回 到 业务 逻辑 层 

e 程序 调用 第 二 个 session 的 update() 方法 持久 这 些 改动 
saveOrUpdate() 做 下 面 的 事 : 

。 如 果 对 象 已 经 在 本 session 中 持久 化 了 ， 不 做 任何 事 


e 如 果 另 一 个 与 本 session 关 联 的 对 象 拥 有 相同 的 持久 化 标识 (identifienm， 抛 出 一 
SB 


o 如 果 对 象 没 有 持久 化 标识 (identifiem) 属 性 ， 对 其 调用 save() 


e 如 果 对 象 的 持久 标识 (identifiem) 表 明 其 是 一 个 新 实例 化 的 对 象 ， 对 其 调 
用 save() 


o 如 果 对 象 是 附带 版 本 信息 的 〈 通 
过 &lt;version&gt; 或 &lt;timestampagt; ) 并 且 版 本 属性 的 值 表明 其 
是 一 个 新 实例 化 的 对 象 ， save() Ce 


e 否则 update() 这 个 对 象 
merge() 可 非常 不 同 : 


e 如 果 session 中 存在 相同 持久 化 标识 (identifier) 的 实例 ， 用 用 户 给 出 的 对 象 的 状 
态 履 盖 上 日 有 的 持久 实例 


e 如 果 session 没 有 相应 的 持久 实例 ， 则 尝试 从 数据 库 中 加 载 ， 或 创建 新 的 持久 化 
实例 


。 最 后 返回 该 持久 实例 
人 


o 用 户 给 出 的 这 个 对 象 没 有 被 关联 到 session 上 ， 它 依旧 是 脱 管 的 


10.8. 删除 持久 对 象 


使 用 Session.delete() 会 把 对 象 的 状态 从 数据 库 中 移 除 。 当然 ， 你 的 应 用 程序 
可 能 仍然 持 有 一 个 指向 已 删除 对 象 的 引用 。 所 以 ， 最 好 这 样 理 解 : delete() 的 用 
途 是 把 一 个 持久 实例 变 成 瞬时 (transient) 实 例 。 


sess.delete(cat); 


你 可 以 用 你 喜欢 的 任何 顺序 删除 对 象 ， 不 用 担心 外 键 约束 冲突 。 当 然 ， 如 果 你 搞 错 
了 顺序 ， 还 是 有 可 能 引发 在 外 键 字 段 定义 的 NOT NULL 约束 冲突 。 例 如 你 删除 了 
父 对 象 ， 但 是 忘记 删除 孩子 们 。 


10.9. EAA FF HE E A) Zl TR 


偶尔 会 用 到 不 重新 生成 持久 化 标识 (identifier)， 将 持久 实例 以 及 其 关联 的 实例 持久 
到 不 同 的 数据 库 中 的 操作 。 


//retrieve a cat from one database 

Session sessioni = factory1.openSession(); 
Transaction tx1 = sessioni.beginTransaction(); 
Cat cat = sessioni.get(Cat.class, catId); 
tx1.commit(); 

sessioni1.close(); 


//reconcile with a second database 

Session session2 = factory2.openSession(); 

Transaction tx2 = session2.beginTransaction(); 
session2.replicate(cat, ReplicationMode.LATEST_VERSION); 
tx2.commit(); 

session2.close(); 


ReplicationMode 决定 在 和 数据 库 中 已 存在 记录 由 冲突 时 ， replicate() 如 何 
处 理 。 


e ReplicationMode.IGNORE - 忽略 它 
e ReplicationMode.OVERWRITE -和 履 盖 相同 的 行 
e ReplicationMode.EXCEPTION - 抛 出 异常 


e ReplicationMode.LATEST_VERSION - 如 果 当 前 的 版 本 较 新 ， 则 和 覆盖 ， 否 则 


这 个 功能 的 用 途 包括 使 录入 的 数据 在 不 同 数据 库 中 一 致 ， 产 品 升级 时 升级 系统 配置 
信息 ， 回 滚 non-ACID 事 务 中 的 修改 等 等 。 (译注 ，non-ACID， 非 ACID;ACID ， 
Atomic > Consistent > Isolated and Durable 的 缩写 ) 


10.10. Session 刷 出 (flush) 
每 间隔 一 段 时 间 ， Session 会 执行 一 些 必 需 的 SQL 语 句 来 把 内 存 中 的 RAK 
同步 到 JDBC 连 接 中 。 这 个 过 程 被 称 为 刷 出 (flush)， 默 认 会 在 下 面 的 时 间 点 执行 
o 在 某 些 查询 执行 之 前 
e 在 调用 org.hibernate.Transaction.commit() 的 时 候 
e 在 调用 Session.flush() 的 时 候 
涉及 的 SQL 语 句 会 按照 下 面 的 顺序 发 出 执行 : 
1. 所 有 对 实体 进行 插入 的 语句 ， 其 顺序 按照 对 象 执行 Session.save() 的 时 间 


顺序 

2. 所 有 对 实体 进行 更 新 的 语句 

3. 所 有 进行 集合 删除 的 语句 

4. 所 有 对 集合 元 素 进行 删除 ， 更 新 或 者 插入 的 语句 

5. 所 有 进行 集合 插入 的 语句 

6. 所 有 对 实体 进行 删除 的 语句 ， 其 顺序 按照 对 象 执行 Session.delete() 的 时 
间 顺 序 


(有 一 个 例外 是 ， 如 果 对 象 使 用 native 方式 来 生成 ID (持久 化 标识 ) 的 话 ， 它 们 
一 执行 Save 就 会 被 插入 。) 


na I flush() 指令 ， 关 于 Session 何 时 会 执行 这 些 JDBC 调 用 是 完 
全 无 法 保证 的 ， 只 能 保证 whats es 前 后 顺序 。 当然 ，Hibernate 保 
证 ， Query.list(..) 绝对 不 会 返回 已 经 失效 的 数据 ， 也 不 会 返回 错误 数据 。 


也 可 以 改变 默认 的 设置 ， 来 让 刷 出 (flush) 操 作 发 生 的 不 那么 频繁 。 FlushMode 类 
定义 了 三 种 不 同 的 方式 。 仅 在 提交 时 刷 出 ( 仅 当 Hibernate 的 Transaction API 被 
使 用 时 有 效 )， 按 照 刚才 说 的 方式 刷 出 ， 以 及 除非 明确 使 用 flush() 否则 从 不 刷 
出 。 最 后 一 种 模式 对 于 那些 需要 长 时 间 保 持 Session 为 打开 或 者 断 线 状态 的 长 时 
间 和 运行 的 工作 单元 很 有 用 。 (参见 第 11.3.2 节 “ 扩 展 周期 的 session 和 自动 版 本 化 ”). 


sess = sf.openSession(); 

Transaction tx = sess.beginTransaction(); 
sess.setFlushMode(FlushMode.COMMIT); // allow queries to return 
stale state 


Cat izi = (Cat) sess.load(Cat.class, id); 
1izi.setName(iznizi); 


// might return stale data 
sess.find("from Cat as cat left outer join cat.kittens kitten"); 


// change to izi is not flushed! 
tx.commit(); // flush occurs 


sess.close(); 


刷 出 (flush) 期 间 ， 可 能 会 抛 出 异常 。 (例如 一 个 DML 操 作 违 反 了 约束 ) 异常 处 理 涉 
及 到 对 Hibernate 事 务 性 行为 的 理解 ， 因 此 我 们 将 在 第 11 章 事务 和 并 发 中 讨论 。 


10.11. 传播 性 持久 化 (transitive persistence) 


对 每 一 个 对 象 都 要 执行 保存 ， 删 除 或 重 关联 操作 让 人 感觉 有 点 麻烦 ， 尤 其 是 在 处 理 
许多 彼此 关联 的 对 象 的 时 候 。 一 个 常见 的 例子 是 父子 关系 。 考 虑 下 面 的 例子 : 


如 果 一 个 父子 关系 中 的 子 对 象 是 值 类 型 (value typed)〈 例 如 ， 地 址 或 字符 串 的 集 
合 ) 的 ， 他 们 的 生命 周期 会 依赖 于 父 对 象 ， 可 以 享受 方便 的 级 联 操作 (Cascading)， 
不 需要 额外 的 动作 。 父 对 象 被 保存 时 ， 这 些 值 类 型 (value typed) 子 对 象 也 将 被 保 
存 ; 父 对 象 被 删除 时 ， 子 对 象 也 将 被 删除 。 这 对 将 一 个 子 对 象 从 集合 中 移 除 是 同样 
有 效 : Hibernate 会 检测 到 ， 并 且 因 为 值 类 型 (value typed) 的 对 象 不 可 能 被 其 他 对 象 
引用 ， 所 以 Hibernate 会 在 数据 库 中 删除 这 个 子 对 象 。 


现在 考虑 同样 的 场景 ， 不 过 父子 对 象 都 是 实体 (entities) 类 型 ， 而 非 值 类 型 (value 
typed) (例如 ， 类 别 与 个 体 ， 或 母 猫 和 小 猫 ) 。 实体 有 自己 的 生命 期 ， 人 允许 共 享 对 
其 的 引用 (因此 从 集合 中 移 除 一 个 实体 ， 不 意味 着 它 可 以 被 删除 ) ， 并 且 实 体 到 其 
他 关联 实体 之 间 默 认 没 有 级 联 操 作 的 设置 。Hibernate 默 认 不 实现 所 谓 的 可 到 达 即 
持久 化 (persistence by reachability) 的 策略 。 


每 个 Hibernate session 的 基本 操作 - 包括 

persist(), merge(), saveOrUpdate(), delete(), lock(), refresh(), ev: 
- 都 有 对 应 的 级 联 风格 (cascade style)。 这 些 级 联 风格 (cascade style) 风 格 分 别 命名 
为 


create, merge, save-update, delete, lock, refresh, evict, replicate 
。 如 果 你 布 望 一 个 操作 被 顺 着 关联 关系 级 联 传播 ， 你 必须 在 映射 文件 中 指出 这 一 
点 。 例 如 : 


<one-to-one name="person" cascade="persist"/> 


级 联 风格 (cascade style) T 224-49: 


<one-to-one name="person" cascade="persist, delete, lock"/> 


你 可 以 使 用 cascade="all" 来 指定 全 部 操作 都 顺 着 关联 关系 级 联 (cascaded)。 K 
认 值 是 cascade="none" ， 即 任何 操作 都 不 会 被 级 联 (cascaded)。 


注意 有 一 个 特殊 的 级 联 风格 (cascade style) delete-orphan ， 只 应 用 于 one-to- 
many 关 联 ， 表 明 delete() 操作 应 该 被 应 用 于 所 有 从 关联 中 删除 的 对 象 。 
建议 : 


o 通常 在 &lt;many-to-one&gt; 或 &lt;many-to-many&gt; 关系 中 应 用 级 联 
(cascade) 没 什么 意义 。 级 联 (cascade) 通 常 在 
&lt;one-to-one&gt; 和 &lt;one-to-many&agt; 关系 中 比较 有 用 。 


。 如 果子 对 象 的 寿命 限定 在 父亲 对 象 的 寿命 之 内 ， 可 通过 指 
Æ cascade="all,delete-orphan" 将 其 变 为 自动 生命 周期 管理 的 对 象 
(lifecycle object) ° 


o 其 他 情况 ， 你 可 根本 不 需要 级 联 (cascade)。 但 是 如 果 你 认为 你 会 经 常 在 某 个 事 
务 中 同时 用 到 父 对 象 与 子 对 象 ， 并 且 你 布 望 少 打点 儿 字 ， 可 以 考虑 使 


用 cascade="persist,merge,save-update" ° 


可 以 使 用 cascade="all" 将 一 个 关联 关系 (无 论 是 对 值 对 象 的 关联 ， 或 者 对 一 个 
集合 的 关联 ) 标记 为 父 / 子 关系 的 关联 。 这样 对 父 对 象 进行 Save/update/delete 操 作 
就 会 导致 子 对 象 也 进行 Save/update/delete 操 作 。 


此 外 ， 一 个 持久 的 父 对 象 对 子 对 象 的 浅 引 用 (mere reference) 会 导致 子 对 象 被 同步 
save/update。 不过， 这 个 隐喻 (metaphor) 的 说 法 并 不 完整 。 除 非 关联 

是 &lt;one-to-many&gt; 关联 并 且 被 标记 为 cascade="delete-orphan" ° © 
则 父 对 象 失去 对 某 个 子 对 象 的 引用 不 会 导致 该 子 对 象 被 自动 删除 。 父子 关系 的 级 联 
(cascading) 操 作 准 确 语义 如 下 : 


o 如 果 父 对 象 被 persist() ， 那 么 所 有 子 对 象 也 会 被 persist() 
o 如 果 父 对 象 被 merge() ， 那 么 所 有 子 对 象 也 会 被 merge() 


o 如 果 父 对 象 被 save() ， update() 或 saveOrUpdate() ， 那 么 所 有 子 对 
象 则 会 被 saveorUpdate() 


。 如 果 某 个 持久 的 父 对 象 引 用 了 瞬时 (transient) 或 者 脱 管 (detached) 的 子 对 象 ， 那 
么 子 对 象 将 会 被 saveOrupdate() 


。 如 果 父 对 象 被 删除 ， 那 么 所 有 子 对 象 也 会 被 delete() 


o 除非 被 标记 为 cascade="delete-orphan" (删除 "孤儿 ?模式 ， 此 时 不 被 任何 
一 个 父 对 象 引 用 的 子 对 象 会 被 删除 ) ， 否则 子 对 象 失掉 父 对 象 对 其 的 引用 时 ， 
什么 事 也 不 会 发 生 。 如 果 有 特殊 需要 ， 应 用 程序 可 通过 显 式 调用 delete() 删 除 
子 对 象 。 


最 后 ， 注 意 操作 的 级 联 可 能 是 在 调用 期 (call time) 或 者 写 入 期 (flush time) Ve A Bl xt He 
图 上 的 。 所 有 的 操作 ， 如 果 允 许 ， 都 在 操作 被 执行 的 时 候 级 联 到 可 触及 的 关联 实体 
上 。 然 而 ， save-upate 和 delete-orphan 是 在 Session flush 的 时 候 才 作用 

到 所 有 可 触及 的 被 关联 对 象 上 的 。 


10.12. 使 用 元 数据 


Hibernate 中 有 一 个 非常 丰富 的 元 级 别 (meta-level) 的 模型 ， 含 有 所 有 的 实体 和 值 类 
型 数据 的 元 数据 。 有 时 这 个 模型 对 应 用 程序 本 身 也 会 非常 有 用 。 比如 说 ， 应 用 程 
序 可 能 在 实现 一 种 “智能 "的 深度 拷贝 算法 时 ， 通 过 使 用 Hibernate 的 元 数据 来 了 解 哪 
些 对 月 应 该 被 拷贝 (比如 ， 可 变 的 值 类 型 数据 ) ， 和 那些 不 应 该 (不 可 变 的 值 类 型 数 
据 ， 也 许 还 有 某 些 被 关联 的 实体 ) 。 


Hibernate 提 供 了 ClassMetadata 接口 ， CollectionMetadata 接口 和 Type Æ 
次 体系 来 访问 元 数据 。 可 以 通过 SessionFactory 获取 元 数据 接口 的 实例 。 


Carte pied =o en ees - 
ClassMetadata catMeta = sessionfactory.getClassMetadata(Cat.clas 


s); 


Object[] propertyValues = catMeta.getPropertyValues(fritz); 
String[] propertyNames = catMeta.getPropertyNames(); 
Type[] propertyTypes = catMeta.getPropertyTypes(); 


// get a Map of all properties which are not collections or asso 
ciations 
Map namedValues = new HashMap(); 
for ( int i=0; i<propertyNames.length; i++ ) { 

if ( !propertyTypes[i].isEntityType() && !propertyTypes[i].i 
sCollectionType() ) { 

namedValues.put( propertyNames[i], propertyValues[i] ); 
} 
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Hibernate 的 事务 和 并 发 控制 很 容易 掌握 。Hibernate 直 接 使 用 JDBC 连 接 和 JTA 资 
源 ， 不 添加 任何 附加 锁定 行为 。 我 们 强烈 推荐 你 花 点 时 间 了 解 JDBC 编 程 ，ANSI 
SQL 查询 语言 和 你 使 用 的 数据 库 系 统 的 事务 隔离 规范 。 


Hibernate 不 锁定 内 存 中 的 对 象 。 你 的 应 用 程序 会 按照 你 的 数据 库 事务 的 隔离 级 别 规 
定 的 那样 运作 。 幸 亏 有 了 Session ， 使 得 Hibernate 通 过 标识 符 查找 ， 和 实体 查询 
(不 是 返回 标量 值 的 报表 查询 ) 提供 了 可 重复 的 读 取 (Repeatable reads) 4 

能 ， Session 同时 也 是 事务 范围 内 的 缓存 (cache) 。 


除了 对 自动 乐观 并 发 控制 提供 版 本 管理 ， 针 对 行 级 悲观 锁定 ，Hibernate 也 提供 了 畏 
助 的 〈 较 小 的 )API， 它 使 用 了 SELECT FOR UPDATE 的 SQL 语法 。 本 章 后 面 会 讨论 
乐观 并 发 控制 和 这 个 API 。 


我 们 从 Configuration 层 、 SessionFactory 层 , 和 Session 层 开 始 讨论 
Hibernate 的 并 行 控制 、 数 据 库 事务 和 应 用 程序 的 长 事务 。 


11.1. Session: ¥ 4 3% M (transaction scope) 


SessionFactory 对 象 的 创建 代价 很 昂贵 ， 它 是 线程 安全 的 对 象 ， 它 为 所 有 的 应 
用 程序 线程 所 共享 。 它 只 创建 一 次 ， 通 常 是 在 应 用 程序 启动 的 时 候 ， 由 一 
个 Configuraion 的 实例 来 创建 。 


Session 对 象 的 创建 代价 比较 小 ， 是 非 线 程 安 全 的 ， 对 于 单个 请 求 ， 单 个 会 话 、 
单个 的 工作 单元 而 言 ， 它 只 被 使 用 一 次 ， 然 后 就 丢弃 。 只 有 在 需要 的 时 候 ， 一 
个 Session 对 象 才 会 获取 一 个 JDBC 的 Connection (或 一 个 Datasource ) 
对 象 ， 因 此 假若 不 使 用 的 时 候 它 不 消费 任何 资源 。 


此 外 我 们 还 要 考虑 数据 库 事务 。 数 据 库 事务 应 该 尽 可 能 的 短 ， 降 低 数 据 库 中 的 锁 争 
用 。 数据 库 长 事务 会 阻止 你 的 应 用 程序 扩展 到 高 的 并 发 负载 。 因 此 ， 假 若 在 用 户 思 
考 期 间 让 数据 库 事务 开 着 ， 直 到 整个 工作 单元 完成 才 关闭 这 个 事务 ， 这 绝 不 是 一 个 
好 的 设计 。 


一 个 操作 单元 (Unit of work) 的 范围 是 多 大 ?单个 的 Hibernate Session 能 跨越 多 个 
数据 库 事务 吗 ? 还 是 一 个 Session 的 作用 范围 对 应 一 个 数据 库 事务 的 范围 ?应 该 
何 时 打开 Session ， 何 时 关闭 Session ?， 你 又 如 何 划 分 数据 库 事务 的 边界 
呢 ? 


11.1.1. 操作 单元 (Unit of work) 


首先 ， 别 用 session-per-operation 这 种 反 模 式 了 ， 也 就 是 说 ， 在 单个 线程 中 ， 不 要 
因为 一 次 简单 的 数据 库 调用 ， 就 打开 和 关闭 一 次 Session ! 数据 库 事务 也 是 如 

此 。 应 用 程序 中 的 数据 库 调 用 是 按照 计划 好 的 次 序 ， 分 组 为 原子 的 操作 单元 。( 注 
意 ， 这 也 意味 着 ， 应 用 程 序 中 ， 在 单个 的 SQL 语句 发 送 之 后 ， 自 动 事务 提交 (auto- 
commib 模 式 失效 了 。 这 种 模式 专门 为 SQL 控制 台 操 作 设 计 的 。 Hibernate 44 1b = BP 
自动 事务 提交 模式 ， 或 者 期 望 应 用 服务 器 禁止 立即 自动 事务 提交 模式 。) 数据 库 事 
务 绝 不 是 可 有 可 无 的 ， 任 何 与 数据 库 之 间 的 通讯 都 必须 在 某 个 事务 中 进行 ， 不 管 你 
是 在 读 还 是 在 写 数据 。 对 读数 据 而 言 ， 应 该 避免 auto-commit 行 为 ， 因 为 很 多 小 的 
事务 比 一 个 清晰 定义 的 工作 单元 性 能 差 。 后 者 也 更 容易 维护 和 扩展 。 


在 多 用 户 的 client/server 应 用 程序 中 ， 最 常用 的 模式 是 每 个 请 求 一 个 会 话 (session- 
per-request)。 在 这 种 模式 下 ， 来 自 客户 端的 请 求 被 发 送 到 服务 器 端 ( 即 Hibernate 
持久 化 层 运行 的 地 方 ) > — 个 新 的 Hibernate Session 被 打开 ， 并 且 执 行 这 个 操 

作 单 元 中 所 有 的 数据 库 操 作 。 一 旦 操作 完成 (同时 对 客户 端的 响应 也 准备 就 绪 ) > 
session 被 同步 ， 然 后 关闭 。 你 也 可 以 使 用 单 个 数据 库 事 务 来 处 理 客户 端 请 求 ， 在 

你 打开 Session 之 后 启动 事务 ， 在 你 关闭 Session 之 前 提交 事务 。 会 话 和 请 求 
之 间 的 关系 是 一 对 一 的 关系 ， 这 种 模式 对 于 大 多 数 应 用 程序 来 说 是 很 棒 的 。 


实现 才 是 昊 正 的 挑战 。Hibernate 内 置 了 对 "当前 session(current session)" 的 管理 ， 
用 于 简化 此 模式 。 你 要 做 的 一 切 就 是 在 服务 器 端 要 处 理 请 求 的 时 候 ， 开 启事 务 ， 在 
响应 发 送 给 客户 之 前 结束 事务 。 你 可 以 用 任何 方式 来 完成 这 一 操作 ， 通 常 的 方案 
有 ServletFilter ， 在 service 方 法 中 进行 pointcut 的 AOP 拦 截 器 ， 或 者 
proxy/interception 容 器 。EJB 容 器 是 实现 横 切 诸如 EJB session bean 上 的 事务 分 
界 ， 用 CMT 对 事务 进行 声明 等 方面 的 标准 手段 。 假 若 你 决定 使 用 编程 式 的 事务 分 
界 ， 请 参考 本 章 后 面 讲 到 的 Hibernate Transaction API， 这 对 多 用 性 和 代码 可 
移植 性 都 有 好 处 。 


在 任何 时 间 ， 任 何 地 方 ， 你 的 应 用 代码 可 以 通过 简单 的 调 

用 sessionFactory.getCurrentSession() 来 访问 "当前 Session"， 用 于 处 理 请 
求 。 你 总 是 会 得 到 当前 数据 库 事务 范围 内 的 Session 。 在 使 用 本 地 资源 或 JTA 环 
境 时 ， 必 须 配 置 它 ， 请 参见 第 2.5 节 “ 上 下 文 相 关 的 (Contextual) Session”。 


有 时， 将 Session 和 数据 库 事务 的 边界 延伸 到 "展示 层 被 演 染 后 "会 带 来 便利 。 有 

些 Serlvet 应 用 程序 在 对 请 求 进行 处 理 后 ， 有 个 单独 的 泻 梁 期 ， 这 种 延伸 对 这 种 程序 
特别 有 用 。 假 若 你 实现 你 自己 的 拦截 器 ， 把 事务 边界 延伸 到 展示 层 演 染 结束 后 非常 
容易 。 然 而 ， 假 若 你 依赖 有 容器 管理 事务 的 EJB， 这 就 不 太 容 易 了 ， 因 为 事务 会 在 
EJB 方 法 返回 后 结 来 ， 而 那 是 在 任何 展示 层 演 染 开始 之 前 。 请 访问 Hibernate 网 站 和 
论坛 ， 你 可 以 找到 Open Session in View 这 一 模式 的 提示 和 示例 。 


11.1.2. Ke 


session-per-request 模 式 不 仅仅 是 一 个 可 以 用 来 设计 操作 单元 的 有 用 概念 。 很 多 业 

务 处 理 都 需 要 一 系列 完整 的 与 用 户 之 间 的 交互 ， 而 这 些 用 户 是 指 对 数据 库 有 交 又 访 
问 的 用 户 。 在 基于 web 的 应 用 和 企业 应 用 中 ， 跨 用 户 交 互 的 数据 库 事务 是 无 法 接受 
的 。 考 虑 下 面 的 例子 : 


@ 在 界面 的 第 一 屏 ， 打 开 对 话 框 ， 用 户 所 看 到 的 数据 是 被 一 个 特定 的 Session 
和 数据 库 事 务 载 入 (load) 的 。 用 户 可 以 随意 修改 对 话 框 中 的 数据 对 象 。 


e 5 分 钟 后 ， 用 户 点 击 “ 保 存 ”"， 期 望 所 做 出 的 修改 被 持久 化 ; 同时 他 也 期 望 自己 是 
唯一 修改 这 个 信息 的 人 ， 不 会 出 现 修改 冲突 。 


从 用 户 的 角度 来 看 ， 我 们 把 这 个 操作 单元 称 为 长 时 间 运 行 的 对 话 (conversation) , 
或 者 (or 应 用 事务 ,application transaction)。 在 你 的 应 用 程序 中 ， 可 以 有 很 多 种 方法 
来 实现 它 。 


头 一 个 幼稚 的 做 法 是 ， 在 用 户 思考 的 过 程 中 ， 人 保持 Session 和 数据 库 事 务 是 打开 
的 ， 保 持 数据 库 锁 定 ， 以 阻止 并 发 修改 ， 从 而 保证 数据 库 事务 隔离 级 别 和 原子 操 
作 。 这 种 方式 当然 是 一 个 反 模 式 ， 因 为 锁 争 用 会 导致 应 用 程序 无 法 扩展 并 发 用 户 的 
数目 。 


很 明显 ， 我 们 必须 使 用 多 个 数据 库 事务 来 实现 这 个 对 话 。 在 这 个 例子 中 ， 维 护 业 务 
处 理 的 事务 隔离 变 成 了 应 用 程序 层 的 部 分 责任 。 一 个 对 话 通常 跨越 多 个 数据 库 事 
务 。 如 果 仅 仅 只 有 一 个 数据 库 事务 (最 后 的 那个 事务 ) 保存 更 新 过 的 数据 ， 而 所 有 
其 他 事务 只 是 单纯 的 读 取 数据 (例如 在 一 个 跨越 多 个 请 求 / 响 应 周期 的 向 导 风 格 的 
对 话 框 中 ) ， 那 么 应 用 程序 事务 将 保证 其 原子 性 。 这 种 方式 比 听 起 来 还 要 容易 实 
现 ， 特 别 是 当 你 使 用 了 Hibernate 的 下 述 特 性 的 时 候 : 


e 自动 版 本 化 - Hibernate 能 够 自动 进行 乐观 并 发 控制 ， 如 果 在 用 户 思考 的 过 程 
中 发 生 并 发 修改 ，Hibernate 能 够 自动 检测 到 。 一 般 我 们 只 在 对 话 结束 时 才 检 


查 。 


e “EZ (Detached Objects) - 如 果 你 决定 采用 前 面 已 经 讨论 过 的 session- 
per-request 模 式 ， 所 有 载 入 的 实例 在 用 户 思 考 的 过 程 中 都 处 于 与 Session 脱 离 
的 状态 。Hibernate 允 许 你 把 与 Session 脱 离 的 对 象 重 新 关联 到 Session 上 ， 并 
且 对 修改 进行 持久 化 ， 这 种 模式 被 称 为 session-per-request-with-detached- 
Objects。 自 动 版 本 化 被 用 来 隔离 并 发 修改 。 


e Extended (or Long) Session - Hibernate 的 Session 可 以 在 数据 库 事 务 提交 
之 后 和 底层 的 JDBC 连 接 断 开 ， 当 一 个 新 的 客户 端 请 求 到 来 的 时 候 ， 它 又 重新 
连接 上 底层 的 JDBC 连 接 。 这 种 模式 被 称 之 为 session-per-conversation， 这 种 
情况 可 能 会 造成 不 必要 的 Session 和 JDBC 连 接 的 重新 关联 。 自 动 版 本 化 被 用 
来 隔离 并 发 修改 ，Session 通常 不 允许 自动 flush, 而 是 明确 flush 。 


session-per-request-with-detached-objects 和 session-per-conversation 44 th tk 
点 ， 我 们 在 本 草 后 面 乐观 并 发 控制 那 部 分 再 进行 讨论 。 


11.1. Session 和 事务 范围 (transaction scope) 
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11.1.3. Kix %47 12 (Considering object 
identity) 


应 用 程序 可 能 在 两 个 不 同 的 Session 中 并 发 访问 同一 持久 化 状态 ， 但 是 ， 一 个 持 
久 化 类 的 实例 无 法 在 两 个 Session 中 共享 。 因 此 有 两 种 不 同 的 标识 语义 : 


数据 库 标 识 

foo.getId().equals( bar.getId() ) 
JVM 标识 

foo==bar 


对 于 那些 关联 到 特定 Session (也 就 是 在 单个 Session 的 范围 内 ) 上 的 对 象 来 
说 ， 这 两 种 标识 的 语义 是 等 价 的 ， 与 数据 库 标 识 对 应 的 JVM 标 识 是 由 Hibernate 来 

保证 的 。 不 过 ， 当 应 用 程序 在 两 个 不 同 的 session 中 并 发 访问 具有 同一 持久 化 标 识 
的 业务 对 象 实例 的 时 候 ， 这 个 业务 对 象 的 两 个 实例 事实 上 是 不 相同 的 (从 JVM 识 别 
RA) 。 这 种 冲突 可 以 通过 在 同步 和 提交 的 时 候 使 用 自动 版 本 化 和 乐 观 锁定 方法 来 
解决 。 


这 种 方式 把 关于 并 发 的 头 疫 问 题 留 给 了 Hibernate 和 数据 库 ; 由 于 在 单个 线程 内 ， 操 
作 单 元 中 的 对 象 识 别 不 需要 代价 兄 贵 的 锁定 或 其 他 意义 上 的 同步 ， 因 此 它 同 时 可 以 
提供 最 好 的 可 伸缩 性 。 只 要 在 单个 线程 只 持 有 一 个 session ， 应 用 程序 就 不 需要 
同步 任何 业务 对 象 。 在 Session 的 范围 内 ， 应 用 程序 可 以 放心 的 使 用 == 进行 对 
象 比 较 。 


不 过 ， 应 用 程序 在 session 的 外 面 使 用 == 进行 对 象 比 较 可 能 会 导致 无 法 预期 的 
结果 。 在 一 些 无 法 预料 的 场合 ， 例 如 ， 如 果 你 把 两 个 脱 管 对 象 实例 放 进 同一 个 

Set 的 时 候 ， 就 可 能 发 生 。 这 两 个 对 象 实例 可 能 有 同一 个 数据 库 标 识 〈 也 就 是 
说 ， 他 们 代表 了 表 的 同一 行 数据 ) ， 从 JVM 标 识 的 定义 上 来 说 ， 对 脱 管 的 对 象 而 
言 ，Hibernate 无 法 保证 他 们 的 的 JVM 标 识 一 致 。 开 发 人 员 必 须 履 盖 持 久 化 类 

的 equals() 方法 和 hashCode() 方法 ， 从 而 实现 自 定 义 的 对 象 相 等 语义 。 警 
告 : 不 要 使 用 数据 库 标识 来 实现 对 象 相等 ， 应 该 使 用 业务 键 值 ， 由 唯一 的 ， 通 常 不 
变 的 属性 组 成 。 当 一 个 瞬时 对 月 被 持久 化 的 时 候 ， 它 的 数据 库 标 识 会 发 生 改 变 。 如 
果 一 个 瞬时 对 象 (通常 也 包括 脱 管 对 象 实例 ) 被 放 入 一 个 Set ， 改 变 它 的 
hashcode 会 导致 与 这 个 Set 的 关系 中 断 。 虽 然 业 务 键 值 的 属性 不 象 数 据 库 主键 那 
样 稳 定 不 变 ， 但 是 你 只 需要 保证 在 同一 个 set 中 的 对 象 属性 的 稳定 性 就 足够 了 。 
请 到 Hibernate 网 站 去 寻求 这 个 问题 更 多 的 详细 的 讨论 。 请 注意 ， 这 不 是 一 个 有 关 
Hibernate 的 问题 ， 而 仅仅 是 一 个 关于 Java 对 象 标识 和 判 等 行为 如 何 实现 的 问题 。 


11.1.4. 常见 问题 


决 不 要 使 用 反 模 式 Session-per-user-session 或 者 session-per-application (当然 ， 
这 个 规定 几乎 没有 例外 ) 。 请 注意 ， 下 述 一 些 问题 可 能 也 会 出 现在 我 们 推荐 的 模式 


中 ， 


在 你 作出 某 个 设计 决定 之 前 ， 请 务必 理解 该 模式 的 应 用 前 提 。 


Session 对 象 是 非 线程 安全 的 。 如 果 一 个 Session 实例 允许 共享 的 话 ， 那 
些 支 持 并 发 运行 的 东 东 ， 例 如 HTTP request，session beans, 或 者 是 Swing 
Workers， 将 会 导致 出 现 资源 争 用 (race condition) 。 如 果 
在 HttpSession 中 有 Hibernate 的 Session 的 话 ( 稍 后 讨论 ) > # 
虑 同步 访问 你 的 Http session。 否则 ， 只 要 用 户 足够 快 的 点 击 浏览 器 
新 ”"， 就 会 导致 两 个 并 发 运行 线程 使 用 同一 个 Session 。 


一 个 由 Hibernate 抛 出 的 异常 意味 着 你 必须 立即 回 滚 数据 库 事务 ， 并 立即 关 

Hl Session  ( 稍 后 会 展开 讨论 ) 。 如 果 你 的 Session 绑 定 到 一 个 应 用 程序 
上 ， 你 必 须 停 止 该 应 用 程序 。 回 滚 数据 库 事务 并 不 会 把 你 的 业务 对 象 退回 到 事 
务 启动 时 候 的 状态 。 这 意味 着 数据 库 状态 和 业务 对 象 状态 不 同步 。 通 常情 况 
下 ， 这 不 是 什么 问题 ， 因 为 异常 是 不 可 恢复 的 ,你 必须 在 回 浓 之 后 重新 开始 执 
行 。 

Session 缓存 了 处 于 持久 化 状态 的 每 个 对 象 (Hibernate 会 监视 和 检查 脏 数 
YE) 。 这 意味 着 ， 如 果 你 让 Session 打开 很 长 一 段 时 间 ， 或 是 仅仅 载 入 了 过 
多 的 数据 ， Session 占用 的 内 存 会 一 直 增 长 ， 直 到 抛 出 
OutOfMemoryException++ $ ° RA 问题 的 一 个 解决 方法 是 调用 clear() 

和 evict() 来 管理 Session 的 缓存 ， 但 是 如 果 你 需要 大 批量 数据 操作 的 

话 ， 最 好 考虑 使 用 存储 过 程 。 在 第 13 章 批量 处 理 (Batch processing) 中 有 
一 些 解决 方案 。 在 用 户 会 话 期 间 一 直 保 持 Session 打开 也 意味 着 出 现 脏 数据 
的 可 能 性 很 高 


你 应 该 考 


oh 


o 


11.2. 数据 库 事务 声明 


数据 库 (或 者 系统 ) 事务 的 声明 总 是 必须 的 。 在 数据 库 事务 之 外 ， 就 无 法 和 数据 库 
通讯 (这 可 能 会 让 那些 习惯 于 自动 提交 事务 模式 的 开发 人 员 感 到 迷惑 ) 。 永 远 使 用 
清晰 的 事务 声明 ， 即 使 只 读 操作 也 是 如 此 。 进 行 显 式 的 事务 声明 并 不 总 是 需要 的 ， 
这 取决 于 你 的 事务 隔离 级 别 和 数据 库 的 能 力 ， 但 不 管 怎么 说 ， 声 明 事务 总 归 有 益 无 
害 。 当 然 ， 一 个 单独 的 数据 库 事务 总 是 比 很 多 琐碎 的 事务 性 能 更 好 ， 即 时 对 读数 据 
而 言 也 是 一 样 。 


一 个 Hibernate 应 用 程序 可 以 运行 在 非 托 管 环境 中 (也 就 是 独立 运行 的 应 用 程序 ， 简 
单 Web 应 用 程序 ， 或 者 Swing 图 形 虽 面 应 用 程序 ) ， 也 可 以 运行 在 托管 的 J2EE 环 
境 中 。 在 一 个 非 托管 环境 中 ，Hibernate 通常 自己 负责 管理 数据 库 连 接 池 。 应 用 程 
序 开 发 人 员 必 须 手 工 设置 事务 声明 ， 换 名 话说 ， 就 是 手工 局 动 ， 提 交 ， 或 者 回 滚 数 
据 库 事 务 。 一 个 托管 的 环境 通常 提供 了 容器 管理 事务 (CMT)， 例 如 事务 装配 通过 可 
E 明 的 方式 定义 在 EJB session beans 的 部 署 描述 符 中 。 可 编程 式 事务 声明 不 再 需 
要 ， 即 使 是 Session 的 同步 也 可 以 自动 完成 。 


让 持久 层 具 备 可 移植 性 是 人 们 的 理想 ,这 种 移植 发 生 在 非 托管 的 本 地 资源 环境 ， 与 依 
赖 JTA 但 是 使 用 BMT 而 非 CMT 的 系统 之 间 。 在 两 种 情况 下 你 都 可 以 使 用 编程 式 的 事 

务 管理 。Hibernate 提 供 了 一 套 称 为 Transaction 的 封装 API|， 用 来 把 你 的 部 署 环 
境 中 的 本 地 事务 管理 系统 转换 到 Hibernate 事 务 上 。 这 个 API 是 可 选 的 ， 但 是 我 们 强 

烈 推荐 你 使 用 ， 除 非 你 用 CMT session bean。 


通常 情况 下 ， 结 束 Session 包含 了 四 个 不 同 的 阶段 : 
e 同步 session(flush, 刷 出 到 磁盘 ) 
。 提交 事务 
e 关闭 Session 
e 处 理 异常 


session 的 同步 (flush, 刷 出 ) 前 面 已 经 讨论 过 了 ， 我 们 现在 进一步 考察 在 托管 和 非 托 
‘eae Fa SS A Fo Ht Ab o 


11.2.1. 非 托 管 环境 


如 果 Hibernat 持 久 层 运行 在 一 个 非 托 管 环境 中 ， 数 据 库 连 接 通 常 由 Hibernate 的 简单 
( 即 非 DataSource) 连 接 池 机 制 来 处 理 。session/transaction 处 理 方 式 如 下 所 示 : 


//Non-managed environment idiom 
Session sess = factory.openSession(); 
Transaction tx = null; 


try { 
tx = sess.beginTransaction(); 


// do some work 


tx.commit(); 


catch (RuntimeException e) { 
if (tx != null) tx.rollback(); 
throw e; // or display error message 


} 
finally { 
sess.close(); 


} 


你 不 需要 显 式 flush() Session -对 commit() 的 调用 会 自动 触发 Session 的 
同 冰 (取决 于 session 的 和 10.10 节 “Session 刷 出 (flush)”)。 调 用 close() 标志 
session 的 结束 。 close() 方法 重要 的 暗示 是 ， session 释放 了 JDBC 连 接 。 这 
段 Java 代 码 在 非 托 管 环境 下 和 JTA 环 境 下 都 可 以 运行 。 


更 加 灵活 的 方案 是 Hibernate 内 置 的 "current session" 上 下 文 管理 ， 前 文 已 经 讲 过 
// Non-managed environment idiom with getCurrentSession() 
try { 


factory.getCurrentSession().beginTransaction(); 


// do some work 


factory.getCurrentSession().getTransaction().commit(); 


catch (RuntimeException e) { 
factory.getCurrentSession().getTransaction().rollback(); 
throw e; // or display error message 


你 很 可 能 从 未 在 一 个 通常 的 应 用 程序 的 业务 代码 中 见 过 这 样 的 代码 片断 : 致命 的 
(系统 ) 异常 应 该 总 是 在 应 用 程序 “顶层 "被 捕获 。 换 句 话 说， 执行 Hibernate 调 用 的 
代码 (在 持久 层 ) 和 处 理 RuntimeException 异常 的 代码 (通常 只 能 清理 和 退出 
应 用 程序 ) 应 该 在 不 同 的 应 用 程序 逻辑 层 。Hibernate 的 当前 上 下 文 管理 可 以 极 大 
地 简化 这 一 设计 ， 你 所 有 的 一 切 就 是 SessionFactory 。 F ARE AEN E 
进行 讨论 2 


请 注意 ， 你 应 该 选择 org. hibernate.transaction. JDBCTransactionFactory 
(这 是 默认 选项 )， 对 第 二 个 例子 来 
说 ，hibernate.current_session_context_class 应 该 是 "thread" 


11.2.2. 使 用 JTA 


如 果 你 的 持久 层 运行 在 一 个 应 用 服务 器 中 (例如 ， 在 EJB session beans 的 后 

面 ) ，Hibernate 获 取 的 每 个 数据 源 连接 将 自动 成 为 全 局 JTA 事 务 的 一 部 分 。 你 可 
以 安装 一 个 独立 的 JTA 实 现 ， 使 用 它 而 不 使 用 EJB。Hibernate 提 供 了 两 种 策略 进行 
JTA 集 成 。 


如 果 你 使 用 bean 管 理事 务 (BMT) ， 可 以 通过 使 用 Hibernate 的 Transaction 
API 来 告诉 应 用 服务 器 启动 和 结束 BMT 事 务 。 因 此 ， 事 务 管理 代码 和 在 非 托 管 环境 
下 是 一 样 的 。 


// BMT idiom 
Session sess = factory.openSession(); 
Transaction tx = null; 


try { 
tx = sess.beginTransaction(); 


// do some work 


tx.commit(); 


catch (RuntimeException e) { 
if (tx != null) tx.rollback(); 
throw e; // or display error message 


} 

finally { 
sess.close(); 

} 


如 果 你 希望 使 用 与 事务 绑 定 的 Session ， 也 就 是 使 用 getCurrentSession() 来 
简化 上 下 文 管理 ， 你 将 不 得 不 直接 使 用 JTA UserTransaction API ° 


// BMT idiom with getCurrentSession() 


try { 
UserTransaction tx = (UserTransaction)new InitialContext() 


. Lookup("java:comp/UserTransaction" ) 


tx.begin(); 


// Do some work on Session bound to transaction 
factory.getCurrentSession().load(...); 
factory.getCurrentSession().persist(...); 


tx.commit(); 


} 

catch (RuntimeException e) { 
tx.rollback(); 
throw e; // or display error message 


在 CMT 方 式 下 ， 事 务 声 明 是 在 session bean 的 部 署 描述 符 中 ， 而 不 需要 编程 。 
此 ， 代 码 被 简化 为 : 


// CMT idiom 
Session sess = factory.getCurrentSession(); 


// do some work 


在 CMT/EJB 中 甚至 会 自动 rollback， 因 为 假若 有 未 捕获 的 RuntimeException 从 
session bean 方 法 中 抛 出 ， 这 就 会 通知 容器 把 全 局 事务 回 滚 。 这 就 意味 着 ， 在 BNMT 
或 者 CMT 中 ， 你 根本 就 不 需要 使 用 Hibernate Transaction API， 你 自动 得 到 了 
绑 定 到 事务 的 “当前 "Session。 


注意 ， 当 你 配置 Hibernate 的 transaction factory 的 时 候 ， 在 直接 使 用 JTA 的 时 候 
(BMT) ， 你 应 该 选 

择 org.hibernate.transaction.JTATransactionFactory ,在 CMT session 
bean 中 选择 org.hibernate.transaction.CMTTransactionFactory 。 记 得 也 要 

设置 hibernate.transaction.manager_lookup_class 。 还 有 ， 确 认 你 

的 hibernate.current_session_context_class 未 设置 (为 了 向 下 兼容 ) ， 或 
者 设置 为 "jta" 。 


getCurrentSession() 在 JTA 环 境 中 有 一 个 弊端 。 对 after_statement 连接 释 
放 方 式 有 一 个 敬告， 这 是 被 默认 使 用 的 。 因 为 JTA 规 范 的 一 个 很 思 奢 的 限制 ， 
Hibernate 不 可 能 自动 清理 任何 未 关闭 的 ScrollableResults 或 者 Iterator ， 
它们 是 由 scroll() 或 iterate() 产生 的 。 你 must 通 过 在 finally RP? BA 


调用 ScrollableResults.close() 或 者 Hibernate.close(Iterator) 方法 来 
释放 底层 数据 库 游 标 。( 当 然 ， 大 部 分 程序 完全 可 以 很 容易 的 避免 在 JTA 或 CMT 代 码 
中 出 现 scroll() 或 iterate() °) 


11.2.3. HH RE 


oF Session 抛 出 异常 (包括 任何 SQLException ), 你 应 该 立即 回 滚 数据 库 事 
务 ， 调 用 Session.close() > K#% Session 实例 。 Session 的 某 些 方法 
可 能 会 导致 session 处 于 不 一 致 的 状态 。 所 有 由 Hibernate 抛 出 的 异常 都 视 为 不 可 以 
恢复 的 。 确 保 在 finally 代码 块 中 调用 close() 方法 ， 以 关闭 掉 Session ° 


HibernateException 是 一 个 非 检 查 期 异常 〈 这 不 同 于 Hibernate 老 的 版 本 ) > € 
封装 了 Hibernate 持 久 层 可 能 出 现 的 大 多 数 错误 。 我 们 的 观点 是 ， 不 应 该 强迫 应 用 程 
序 开 发 人 员 在 底层 捕获 无 法 恢复 的 异常 。 在 大 多 数 软件 系统 中 ， 非 检查 期 异常 和 致 
命 异常 都 是 在 相应 方法 调用 的 堆栈 的 顶层 被 处 理 的 (也 就 是 说 ， 在 软件 上 面 的 逻辑 
B) ， 并 且 提 供 一 个 错误 信 oe (或 者 采取 其 他 某 些 相应 的 操 
Ve) 。 请 注意 ，Hibernate 也 有 可 能 其 他 并 不 属于 HibernateException 的 非 
检查 期 异常 。 ee， > 应 该 采取 某 些 相应 的 操作 去 处 理 。 


在 和 数据 库 进 行 交 互 时 ，Hibernate 把 捕获 的 SQLException 封装 为 Hibernate 的 
JDBCException 。 事 实 上 ，Hibernate 尝 试 把 异常 转换 为 更 有 实际 含义 

的 JDBCException 异常 的 子 类 。 底 层 的 SQLException 可 以 通 

过 JDBCException.getCause() 来 得 到 。Hibernate 通 过 使 用 关联 到 
SessionFactory 上 的 SQLExceptionConverter 来 把 SQLException 转换 为 
一 个 对 应 的 JDBCException A Riž eo RUHIL 

下 ， SQLExceptionConverter 可 以 通过 配置 dialect 选项 指定 ; 此 外 ， 也 可 以 使 
用 用 户 自 定义 的 实现 类 (参考 javadocs SQLExceptionconverterFactory 类 来 了 
解 详情 ) 。 标 准 的 JDBCException 子 类 型 是 : 


e JDBCConnectionException -指明 底层 的 JDBC 通 讯 出 现 错误 
e SQLGrammarException -指明 发 送 的 SQL 语 句 的 语法 或 者 格式 错误 
e ConstraintViolationException -指明 某 种 类 型 的 约束 违例 错误 


e LockAcquisitionException -指明 了 在 执行 请 求 操作 时 ， 获 取 所 需 的 锁 级 
别 时 出 现 的 错误 。 


e GenericJDBCException -不 属于 任何 其 他 种 类 的 原生 异常 


11.2.4. 事务 超时 


EJB 这 样 的 托管 环境 有 一 项 极为 重要 的 特性 ， 而 它 从 未 在 非 托管 环境 中 提供 过 ， 那 
就 是 事务 超时 。 在 出 现 错 误 的 事务 行为 的 时 候 ， 超 时 可 以 确保 不 会 无 限 挂 起 资源 、 
对 用 户 没 有 交代 。 在 托管 (JTA) 环 境 之 外 ，Hibernate 无 法 完全 提供 这 一 功能 。 但 
是 ，Hiberante 至 少 可 以 控制 数据 访问 ， 确 保 数 据 库 级 别 的 死 锁 ， 和 返回 巨大 结果 集 
的 查询 被 限定 在 一 个 规定 的 时 间 内 。 在 托管 环境 中 ，Hibernate 会 把 事务 超时 转交 给 
JTA。 这 一 功能 通过 Hibernate Transaction 对 象 进 行 抽象 。 


Session sess = factory.openSession(); 


try { 
//set transaction timeout to 3 seconds 


sess.getTransaction().setTimeout(3); 
sess.getTransaction().begin(); 


// do some work 


sess.getTransaction().commit() 


catch (RuntimeException e) { 
sess.getTransaction().rollback(); 
throw e; // or display error message 


} 

finally { 
sess.close(); 

} 


注意 setTimeout() 不 应 该 在 CMT bean 中 调用 ， 此 时 事务 超时 值 应 该 是 被 声明 式 
定义 的 。 


11.3. 乐观 并 发 控制 (Optimistic concurrency 
control) 


唯一 能 够 同时 保持 高 并 发 和 高 可 伸缩 性 的 方法 就 是 使 用 带 版 本 化 的 乐观 并 发 控制 。 
版 本 检查 使 用 版 本 号 、 或 者 时 间 惟 来 检测 更 新 冲突 (并 且 防 止 更 新 丢失 ) 。 
Hibernate 为 使 用 乐观 并 发 控制 的 代码 提供 了 三 种 可 能 的 方法 ， 应 用 程序 在 编写 这 
些 代码 时 ， 可 以 采用 它们 。 我 们 已 经 在 前 面 应 用 程序 对 话 那 部 分 展示 了 乐观 并 发 控 
制 的 应 用 场景 ， 此 外 ， 在 单个 数据 库 事务 范围 内 ， 版 本 检查 也 提供 了 防止 更 新 丢失 
的 好 处 。 


11.3.1. 应 用 程序 级 别 的 版 本 检查 (Application 
version checking) 


未 能 充分 利用 Hibernate 功 能 的 实现 代码 中 ， 每 次 和 数据 库 交 互 都 需要 一 个 新 的 
RAR ， 而且 开发 人 员 必 须 在 显示 数据 之 前 从 数据 库 中 重 新 载 入 所 有 的 持久 化 
对 象 实例 。 这 种 方式 迫使 应 用 程序 自己 实现 版 本 检查 来 确保 对 话 事务 的 隔离 ， 从 数 

据 访 问 的 角度 来 说 是 最 低 效 的 。 这 种 使 用 方式 和 entity EJB 最 相似 。 


// foo is an instance loaded by a previous Session 
session = factory.openSession(); 
Transaction t = session.beginTransaction(); 


int oldVersion = foo.getVersion(); 

session.load( foo, foo.getKey() ); // load the current state 

if ( oldVersion!=foo.getVersion ) throw new StaleObjectStateExce 
ption(); 

foo.setProperty("bar"); 


t.commit(); 
session.close(); 


version 属性 使 用 &lt;version&agt; RRA? w RAR 是 脏 数据 ， 在 同步 的 
时 候 ，Hibernate 会 自动 增加 版 本 号 。 


当然 ， 如 果 你 的 应 用 是 在 一 个 低 数据 并 发 环境 下 ， 并 不 需要 版 本 检查 的 话 ， 你 照样 
可 以 使 用 这 种 方式 ， 只 不 过 跳 过 版 本 检查 就 是 了 。 在 这 种 情况 下 ， 最 晚 提交 生效 
(last commit wins) 就 是 你 的 长 对 话 的 默认 处 理 策略 。 请 记 住 这 种 策略 可 能 会 让 

应 用 软件 的 用 户 感到 困惑 ， 因 为 他 们 有 可 能 会 碰 上 更 新 丢失 掉 却 没有 出 错 信 息 ， 或 
者 需要 合并 更 改 冲 突 的 情况 。 


很 明显 ， 手 工 进 行 版 本 检查 只 适合 于 某 些 软件 规模 非常 小 的 应 用 场景 ， 对 于 大 多 数 
软件 应 用 场景 来 说 并 不 现实 。 通 常情 况 下 ， 不 仅 是 单个 对 象 实 例 需 要 进行 版 本 检 
查 ， 整 个 被 修改 过 的 关 联 对 象 图 也 都 需要 进行 版 本 检查 。 作 为 标准 设计 范例 ， 
Hibernate 使 用 扩展 周期 的 Session 的 方式 ， 或 者 脱 管 对 象 实 例 的 方式 来 提供 自 
动 版 本 检查 。 


11.3.2. 扩展 周期 的 session 和 自动 版 本 化 


单个 Session 实例 和 它 所 关联 的 所 有 持久 化 对 象 实 例 都 被 用 于 整个 对 话 ， 这 被 称 
为 Session-perconversation。Hibernate 在 同步 的 时 候 进 行 对 象 实例 的 版 本 检查 ， 
ee A aes Rie a ol les Uae a 
(通常 的 抉择 是 给 用 户 提供 一 个 合并 更 改 ， 或 者 在 无 脏 数据 情况 下 重新 进行 业务 对 
er 


在 等 待 用 户 交 互 的 时 候 ， Session 断 开 底层 的 JDBC 连 接 。 这 种 方式 以 数据 库 访 
问 的 角度 来 说 是 最 高 效 的 方式 。 应 用 程序 不 需要 关心 版 本 检查 或 脱 管 对 象 实 例 的 重 
新 关联 ， 在 每 个 数据 库 事务 中 ， 应 用 程序 也 不 需要 载 入 读 取 对 象 实例 。 


// foo is an instance loaded earlier by the old session 
Transaction t = session.beginTransaction(); // Obtain a new JDBC 
connection, start transaction 


foo.setProperty("bar"); 


session.flush(); // Only for last transaction in conversation 
t.commit(); // Also return JDBC connection 
session.close(); // Only for last transaction in conversation 


foo 对 象 知道 它 是 在 哪个 Session 中 被 装 入 的 。 在 一 个 昌 session 中 开局 一 个 新 
的 数据 库 事务 ， 会 导致 session 获 取 一 个 新 的 连接 ， 并 恢复 session 的 功能 。 将 数据 
库 事 务 提交 ， 使 得 session 从 JDBC 连 接 断 开 > 并 将 此 连接 交还 给 连接 池 。 在 重新 连 
接 之 后 ， 要 强制 对 你 没有 更 新 的 数据 进行 一 次 版 本 检查 ， 你 可 以 对 所 有 可 能 被 其 他 
事务 修改 过 的 对 象 ， 使 用 参数 LockMode .READ 来 调用 Session.lock() 。 你 不 
用 lock 任 何 你 正在 更 新 的 数据 。 一 般 你 会 在 扩展 的 Session 上 设 

置 FLlushMode .NEVER ， 因 此 只 有 最 后 一 个 数据 库 事务 
中 发 生 的 修改 发 送 到 数据 库 。 因 此 ， 只 有 这 最 后 一 次 数据 库 事 务 才 会 

含 flush() 操作 ， 然 后 在 整个 对 话 结束 后 ， 还 要 close() 这 Rn o 


如 果 在 用 户 思 考 的 过 程 中 ， Session 因为 太 大 了 而 不 能 保存 ， 那 么 这 种 模式 是 有 
问题 的 。 举 例 来 说 ， 一 个 HttpSession 应 该 尽 可 能 的 小 。 由 于 Session 是 一 级 
缓存 ， 并 且 保 持 了 所 有 被 载 入 过 的 对 象 ， 因 此 我 们 只 应 该 在 那些 少量 的 
request/response 情况 下 使 用 这 种 策略 。 你 应 该 只 把 一 个 Session 用 于 单个 对 
话 ， 因 为 它 很 快 就 会 出 现 脏 数据 。 


(注意 ， 早 期 的 Hibernate 版 本 需要 明确 的 对 Session 进行 disconnec 和 
reconnect。 这 些 方法 现在 已 经 过 时 了 ， 打 开 事 务 和 关闭 事务 会 起 到 同样 的 效果 。 ) 


此 外 ， 也 请 注意 ， 你 应 该 让 与 数据 库 连 接 断 开 的 Session 对 持久 层 保持 关闭 状 
态 。 换 和 句 话 说 ， 在 三 层 环境 中 ， 使 用 有 状态 的 EJB session bean 来 持 

有 Session ， 而 不 要 把 它 传 递 到 Web 层 (其 至 把 它 序列 化 到 一 个 单独 的 层 ) ， 保 
存在 HttpSession 中 。 


扩展 session 模 式 ， 或 者 被 称 为 每 次 对 话 一 个 session(session-per-conversation), 在 
与 自动 管理 当前 session 上 下 文联 用 的 时 候 会 更 困难 。 你 需要 提供 你 自己 


2a 一 


的 CurrentSessionContext 实现 。 请 参阅 Hibernate Wiki 以 获得 示例 。 


11.3.3. 脱 管 对 象 (deatched object) 和 自动 版 本 化 


这 种 方式 下 ， 与 持久 化 存储 的 每 次 交互 都 发 生 在 一 个 新 的 Session Po 然而 ， 同 
一 持久 化 对 象 实例 可 以 在 多 次 与 数据 库 的 交互 中 重用 。 应 用 程序 操纵 脱 管 对 象 实例 
的 状态 ， 这 个 脱 管 对 象 实例 最 初 是 在 另 一 个 Session 中 载 入 的 ， 然 后 调用 
Session.update() ， Session.saveOrUpdate() ,或 者 Session.merge() 
来 重新 关联 该 对 象 实 例 。 


// foo is an instance loaded by a previous Session 
foo.setProperty("bar"); 

session = factory.openSession(); 

Transaction t = session.beginTransaction(); 
session.saveOrUpdate(foo); // Use merge() if "foo" might have be 
en loaded already 

t.commit(); 

session.close(); 


Hibernate 会 再 一 次 在 同步 的 时 候 检 查 对 象 实例 的 版 本 ， 如 果 发 生 更 新 冲突 ， 就 抛 出 
异常 。 
如 果 你 确信 对 象 没有 被 修改 过 ， 你 也 可 以 调用 lock() 来 设置 

LockMode.READ 〈 绕 过 所 有 的 缓存 ， 执 行 版 本 检查 ) ， 从 而 取代 update() 操 
作 。 


11.3.4. 定制 自动 版 本 化 行为 


对 于 特定 的 属性 和 集合 ， 通 过 为 它们 设置 映射 属性 optimistic-lock 的 值 
为 false ， 来 禁止 Hibernate 的 版 本 自动 增加 。 这 样 的 话 ， 如 果 该 属性 腑 数据 ， 
Hibernate 将 不 再 增加 版 本 号 。 


遗留 系统 的 数据 库 Schema 通 常 是 静态 的 ， 不 可 修改 的 。 或 者 ， 其 他 应 用 程序 也 可 
能 访问 同一 数据 库 ， 根 本 无 法 得 知 如 何 处 理 版 本 号 ， 甚 至 时 间 戳 。 在 以 上 的 所 有 场 
景 中 ， 实 现 版 本 化 不 能 依靠 数据 库 表 的 某 个 特定 列 。 在 &lt;class&gt; 的 映射 中 
设置 optimistic-lock="all" 可 以 在 没有 版 本 或 者 时 间 玲 属性 映射 的 情况 下 实 
HL 版 本 检查 ， 此 时 Hibernate 将 比较 一 行 记 录 的 每 个 字段 的 状态 。 请 注意 ， 只 有 当 
Hibernate 能 够 比 较 新 日 状态 的 情况 下 ， 这 种 方式 才能 生效 ， 也 就 是 说 ， 你 必须 使 
用 单个 长 生命 周期 Session 模式 ， 而 不 能 使 用 session-per-request-with- 
detached-objects 模 式 。 


有 些 情况 下 ， 只 要 更 改 不 发 生 交 错 ， 并 发 修改 也 是 允许 的 。 当 你 
在 &lt;class&gt; 的 映射 中 设置 optimistic-lock="dirty" ，Hibernate 在 同 
步 的 时 候 将 只 比较 有 脏 数据 的 字段 。 


在 以 上 所 有 场景 中 ， 不 管 是 专门 设置 一 个 版 本 /时 间 戳 列 ， 还 是 进行 全 部 字段 / 脏 数 
据 字 段 比较 ，Hibernate 都 会 针对 每 个 实体 对 象 发 送 一 条 UPDATE (〈 带 有 相应 的 
WHERE 语句 ) 的 SQL 语 匈 来 执行 版 本 检查 和 数据 更 新 。 如 果 你 对 关联 实体 设置 级 
联 关系 使 用 传播 性 持久 化 (transitive persistence) ， 那 么 Hibernate 可 能 会 执行 不 
必要 的 Update 语 句 。 这 通常 不 是 个 问题 ， 但 是 数据 库 里 面 对 on update RK 的 触发 
器 可 能 在 脱 管 对 象 没 有 任何 更 改 的 情况 下 被 触发 。 因 此 ， 你 可 以 在 
&lt;class&gt; 的 映射 中 ， 通 过 设置 select-before-update="true" 来 定制 
这 一 行为 ， 强 制 Hibernate SELECT 这 个 对 象 实例 ， 从 而 保证 ， 在 更 新 记录 之 前 ， 
对 象 的 确 是 被 修改 过 。 


11.4. EUM £ (Pessimistic Locking) 


用 户 其 实 并 不 需要 花 很 多 精力 去 担心 锁定 策略 的 问题 。 通 常情 况 下 ， 只 要 为 JDBC 
连接 指定 一 下 隔 离 级 别 ， 然 后 让 数据 库 去 搞定 一 切 就 够 了 。 然 而 ， 高 级 用 户 有 时 候 
希望 进行 一 个 排 它 的 悲观 锁定 ， 或 者 在 一 个 新 的 事务 局 动 的 时 候 ， 重 新 进行 锁定 。 
Hibernate 总 是 使 用 数据 库 的 锁定 机 制 ， 从 不 在 内 存 中 锁定 对 象 ! 


类 LockMode 定义 了 Hibernate 所 需 的 不 同 的 锁定 级 别 。 一 个 锁定 可 以 通过 以 下 的 
机 制 来 设置 : 
e 当 Hibernate 更 新 或 者 插入 一 行 记录 的 时 候 ， 锁 定 级 别 自动 设置 
为 LockMode .WRITE 。 


eo 当 用 户 显 式 的 使 用 数据 库 支 持 的 SQL 格 式 SELECT ... FOR UPDATE 发 送 
SQL 的 时 候 ， 锁 定 级 别 设 置 为 LockMode .UPGRADE 


e 当 用 户 显 式 的 使 用 Oracle 数 据 库 的 SQL 语 
6] SELECT ... FOR UPDATE NOWAIT 的 时 候 ， 锁 定 级 别 设 
置 LockMode.UPGRADE_NOWAIT 

e 当 Hibernate 在 “可 重复 读 ?" 或 者 是 "序列 化 "数据 库 隔 离 级 别 下 读 取 数 据 的 时 候 ， 
锁定 模式 自动 设置 为 LockMode ,READ 。 这 种 模式 也 可 以 通过 用 户 显 式 指定 进 
行 设置 ° 

e LockMode.NONE 代表 无 需 锁定 。 在 Transaction 结束 时 ， 所 有 的 对 得 都 
切换 到 该 模式 上 来 。 与 Session 相关 联 的 对 象 通过 调用 update() 或 
者 saveOrupdate() 脱离 该 模式 。 


" 显 式 的 用 户 指定 "可 以 通过 以 下 几 种 方式 之 一 来 表示 : 
e 调用 Session.load() 的 时 候 指定 锁定 模式 (LockMode) ° 
e 调用 Session.lock() ° 
e 调用 Query.setLockMode() ° 


如 果 在 UPGRADE 或 者 UPGRADE_NOWAIT 锁定 模式 下 调用 Session.load() ， 并 
且 要 读 取 的 对 象 尚 未 被 session 载 入 过 ， 那 么 对 象 通 

过 SELECT ... FOR UPDATE 这 样 的 SQL 语 句 被 载 入 。 如 果 为 一 个 对 象 调 用 
load() 方法 时 ， 该 对 象 已 经 在 另 一 个 较 少 限制 的 锁定 模式 下 被 载 入 了 ， 那 A 
Hibernate 就 对 该 对 象 调 用 lock() 方法 。 


如 果 指 定 的 锁定 模式 是 READ , UPGRADE 或 UPGRADE NOWAIT ， 那 

么 Session.lock() 就 执行 版 本 号 检查 。 (在 UPGRADE 或 

者 UPGRADE_NOWAIT 锁定 模式 下 ， 执 行 SELECT ... FOR UPDATE 这 样 的 SQL 语 
aJo) 


如 果 数 据 库 不 支持 用 户 设 置 的 锁定 模式 ，Hibernate 将 使 用 适当 的 替代 模式 (而 不 是 
扔 出 异常 ) 。 这 一 点 可 以 确保 应 用 程序 的 可 移植 性 。 


11.5. 连接 释放 模式 (Connection Release Modes) 


Hibernate 关 于 JDBC 连 接管 理 的 日 (2.X) 行 为 是 ， Session 在 第 一 次 需要 的 时 候 获 
取 一 个 连接 ， 在 session 关 闭 之 人 一 直 会 持 有 这 个 连接 。Hibernate 引 入 了 连接 释放 
的 概念 ， 来 告诉 Session 如 何 处 理 它 的 JDBC 和 连接。 注意， 下 面 的 讨论 只 适用 于 采用 
配置 ConnectionProvider 来 提供 连接 的 情况 ， 用 户 自己 提供 的 连接 与 这 里 的 讨 
论 无 关 。 通 过 org.hibernate.ConnectionReleaseMode 的 不 同 枚 举 值 来 使 用 不 
用 的 释放 模式 : 


ON_CLOSE -基本 上 就 是 上 面 提 到 的 老式 行为 。Hibernate session 在 第 一 次 需 
要 进行 JDBC 操 作 的 时 候 获取 连接 ， 然 后 持 有 它 ， 直 到 session 关 闭 。 


AFTER_TRANSACTION -在 org.hibernate.Transaction 结束 后 释放 连 
接 。 

AFTER_STATEMENT (也 被 称 做 积极 释放 ) - 在 每 一 条 语句 被 执行 后 就 释放 连 
接 。 但 假若 语句 留 下 了 与 Session 相 关 的 资源 ， 那 就 不 会 被 释放 。 目 前 唯一 的 这 
种 情形 就 是 使 用 org.hibernate.ScrollableResults ° 


hibernate.connection.release mode 配置 参数 用 来 指定 使 用 哪 一 种 释放 模 
式 。 可 能 的 值 有 : 


auto (RU) - 这 一 选择 把 释放 模式 委派 
给 org.hibernate. transaction. TransactionFactory.getDefaultRelease 
方法 。 对 JTATransactionFactory 来 说 ， 它 会 返回 
ConnectionReleaseMode.AFTER_STATEMENT 对 JDBCTransactionFactory 
来 说 ， 则 是 ConnectionReleaseMode.AFTER TRANSACTION“。 很 少 需要 修 
改 这 一 默认 行为 ， 因 为 假若 设置 不 当 ， 就 会 带 来 DUg， 或 者 给 用 户 代码 带 来 误 


Go 


on_close -使 用 ConnectionReleaseMode.ON_CLOSE. 这 种 方式 是 为 了 向 
下 兼容 的 ,但 是 已 经 完全 不 被 鼓励 使 用 了 。 


after_transaction -使 用 
ConnectionReleaseMode.AFTER_TRANSACTION 。 这 一 设置 不 应 该 在 JTA 环 
境 下 使 用 。 也 要 注意 ， 使 用 
ConnectionReleaseMode.AFTER_TRANSACTION 的 时 候 ， 假 若 session 处 于 
auto-commit 状 态 ， 连 接 会 像 AFTER_STATEMENT 那 样 被 释放 。 


after_statement -使 用 ConnectionReleaseMode.AFTER_STATEMENT 。 
除 此 之 外 ， 会 查询 配置 的 ConnectionProvider ， 是 否 它 支 持 这 一 设置 

(( supportsAggressiveRelease() )) 。 假 若 不 支持 ， 释 放 模 式 会 被 设置 为 
ConnectionReleaseMode.AFTER _TRANSACTION。 只 有 在 你 每 次 调 

用 ConnectionProvider.getConnection() 获取 底层 JDBC 连 接 的 时 候 ， 都 
可 以 确信 获得 同一 个 连接 的 时 候 ， 这 一 设置 才 是 安全 的 ; 或 者 在 auto-commit 
环境 中 ， 你 可 以 不 管 是 否 每 次 都 获得 同一 个 连接 的 时 候 ， 这 才 是 安全 的 。 


11.5. 连接 释放 模式 (Connection Release Modes) 


456 
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应 用 程序 能 够 响应 Hibernate 内 部 产生 的 特定 事件 是 非常 有 用 的 。 这 样 就 允许 实现 某 
些 通用 的 功能 以 及 允许 对 Hibernate 功 能 进行 扩展 。 


12.1. 42 %& & (Interceptors) 


Interceptor 接口 提供 了 从 会 话 (session) 回 调 (callback) 应 用 程序 (application) 的 
机 制 ， 这 种 回调 机 制 可 以 允许 应 用 程序 在 持久 化 对 象 被 保存 、 更 新 、 删 除 或 是 加 载 
之 前 ， 检 查 并 (或 ) 修改 其 属性 。 一 个 可 能 的 用 途 ， 就 是 用 来 跟踪 审核 (auditing) 
信息 。 例 如 : 下 面 的 这 个 拦截 器 ， 会 在 一 个 实现 了 auditable 接口 的 对 象 被 创 
建 时 自动 地 设置 createTimestamp 属性 ， 并 在 实现 了 Auditable 接口 的 对 象 被 
更 新 时 ， 同 步 更 新 lastUpdateTimestamp 属性 。 


你 可 以 直接 实现 Interceptor 接口 ， 也 可 以 〈 最 好 ) 继承 
自 EmptyInterceptor ° 


package org.hibernate.test; 


import java.io.Serializable; 
import java.util.Date; 
import java.util.Iterator; 


import org.hibernate.EmptyInterceptor; 
import org.hibernate.Transaction; 
import org.hibernate.type.Type; 


public class AuditInterceptor extends EmptyInterceptor { 


private int updates; 
private int creates; 
private int loads; 


public void onDelete(Object entity, 
Serializable id, 
Object[] state, 
String[] propertyNames, 
Type[] types) { 
// do nothing 
} 


public boolean onFlushDirty(Object entity, 
Serializable id, 
Object[] currentState, 
Object[] previousState, 
String[] propertyNames, 


Type[] types) { 


if ( entity instanceof Auditable ) { 
updates++; 
for ( int i=0; i < propertyNames.length; i++ ) { 
if ( "lastUpdateTimestamp".equals( propertyNames 


[i] ) ) { 


currentState[i] = new Date(); 


return true; 


} 


return false; 


} 


public boolean onLoad(Object entity, 
Serializable id, 
Object[] state, 
String[] propertyNames, 
Type[] types) { 
if ( entity instanceof Auditable ) { 
loads++; 


return false; 


} 


public boolean onSave(Object entity, 
Serializable id, 
Object[] state, 
String[] propertyNames, 


Type[] types) { 


if ( entity instanceof Auditable ) { 
creates++; 
for ( int i=0; i<propertyNames.length; i++ ) { 
if ( "createTimestamp".equals( propertyNames[i] 


)) í 
state[i] = new Date(); 
return true; 
} 
} 
} 
return false; 
} 


public void afterTransactionCompletion(Transaction tx) { 
if ( tx.wasCommitted() ) { 


System.out.printin("Creations: " + creates + ", Upda 
tes: " + updates, "Loads: " + loads); 
} 
updates=0; 
creates=0; 
loads=0; 


拦截 器 可 以 有 两 种 : Session 范围 内 的 ， 和 SessionFactory 范围 内 的 。 


当 使 用 某 个 重 载 的 SessionFactory.openSession() 使 用 Interceptor 作为 参数 调 
用 打开 一 个 Session 的 时 候 ， 就 指定 了 Session 范围 内 的 拦截 器 。 


Session session = sf.openSession( new AuditInterceptor() ) 


SessionFactory 范围 内 的 拦截 器 要 通过 Configuration 中 注册 ， 而 这 必须 在 
创建 SessionFactory 之 前 。 在 这 种 情况 下 ， 给 出 的 拦截 器 会 被 这 

个 SessionFactory 所 打开 的 所 有 session 使 用 了 ; 除非 Session 打开 时 明确 指明 了 
使 用 的 拦截 器 。 SessionFactory 范围 内 的 拦截 器 ， 必 须 是 线程 安全 的 ， 因 为 多 
个 session 可 能 并 发 使 用 这 个 拦截 器 ， 要 因此 小 心 不 要 保存 与 session 相关 的 状态 。 


new Configuration().setInterceptor( new AuditInterceptor() ); 


12.2. 事件 系统 (Event system) 


如 果 需 要 响应 持久 层 的 某 些 特殊 事件 ， 你 也 可 以 使 用 Hibernate3 的 事件 框架 。 该 事 
件 系统 可 以 用 来 替代 拦截 器 ， 也 可 以 作为 拦截 器 的 补充 来 使 用 。 


基本 上 ， Session 接口 的 每 个 方法 都 有 相对 应 的 事件 。 比 如 

LoadEvent ， FlushEvent ， 等 等 《查阅 XML 配置 文件 的 DTD， 以 

及 org.hibernate.event 包 来 获得 所 有 已 定义 的 事件 的 列表 ) o BREA 法 被 
调用 时 ，Hibernate Session 会 生成 一 个 相对 应 的 事件 并 激活 所 有 配置 好 的 事件 
监听 器 。 系 统 预 设 的 监听 器 实现 的 处 理 过 程 就 是 被 监听 的 方法 要 做 的 (被 监听 的 方 
法 所 做 的 其 实 仅 仅 是 激活 监听 器 ，“ 实 际 ” 的 工作 是 由 监听 器 完成 的 ) 。 不 过 ， 你 可 
以 自由 地 选择 实现 一 个 自己 定制 的 监听 器 (比如 ， 实 现 并 注册 用 来 处 理 处 
理 LoadEvent 的 LoadEventListener 接口 ) ， 来 负责 处 理 所 有 的 调 

用 Session 的 load() 方法 的 请 求 。 


监听 器 应 该 被 看 作 是 单 例 (Singleton) 对 象 ， 也 就 是 说 ， 所 有 同类 型 的 事件 的 处 理 共 
享 同一 个 监听 器 实例 ， 因 此 监听 器 不 应 该 保存 任何 状态 (也 就 是 不 应 该 使 用 成 员 变 
量 ) 。 


用 户 定 制 的 监听 器 应 该 实现 与 所 要 处 理 的 事件 相对 应 的 接口 ， 或 者 从 一 个 合适 的 基 
类 继承 (甚至 是 从 Hibernate 自 带 的 默认 事件 监听 器 类 继承 ， 为 了 方便 你 这 样 做 ， 
这 些 类 都 被 声明 成 non-final 的 了 ) 。 用 户 定制 的 监听 器 可 以 通过 编程 使 

用 Configuration 对 象 来 注册 ， 也 可 以 在 Hibernate 的 XML 格 式 的 配置 文件 中 进 
行 声明 (不 支持 在 Properties 格 式 的 配置 文件 声明 监听 器 ) 。 下 面 是 一 个 用 户 定制 
的 加 载 事 件 (load event) 的 监听 器 : 


public class MyLoadListener implements LoadEventListener { 
// this is the single method defined by the LoadEventListene 
r interface 
public void onLoad(LoadEvent event, LoadEventListener.LoadTy 
pe loadType) 
throws HibernateException { 
if ( !MySecurity.isAuthorized( event.getEntityClassName( 
), event.getEntityId() ) ) { 
throw MySecurityException("Unauthorized access"); 
} 


w 


你 还 需要 修改 一 处 配置 ， 来 告诉 Hibernate， 除 了 默认 的 监听 器 ， 还 要 附加 选 定 的 监 


<hibernate-configuration> 
<session-factory> 


<event type="load"> 
<listener class="com.eg.MyLoadListener"/> 
<listener class="org.hibernate.event.def.DefaultLoad 
EventListener"/> 
</event> 
</session-factory> 
</hibernate-configuration> 


看 看 用 另 一 种 方式 ， 通 过 编程 的 方式 来 注册 它 。 


Configuration cfg = new Configuration(); 

LoadEventListener[] stack = { new MyLoadListener(), new DefaultL 
oadEventListener() }; 
cfg.EventListeners().setLoadEventListeners(stack); 


通过 在 XML 配置 文件 声明 而 注册 的 监听 器 不 能 共享 实例 。 如 果 在 多 

个 @lt;listener/agt; 节点 中 使 用 了 相同 的 类 的 名 字 ， 则 每 一 个 引用 都 将 会 产 
生 一 个 独立 的 实例 。 如 果 你 需要 在 多 个 监听 器 类 型 之 间 共 享 监听 器 的 实例 ， 则 你 必 
须 使 用 编程 的 方式 来 进行 注册 。 


为 什么 我 们 实现 了 特定 监听 器 的 接口 ， 在 注册 的 时 候 还 要 明确 指出 我 们 要 注册 哪个 
事件 的 监听 器 呢 ? 这 是 因为 一 个 类 可 能 实现 多 个 监听 器 的 接口 。 在 注册 的 时 候 明 确 
指定 要 监听 的 事件 ， 可 以 让 启用 或 者 禁用 对 某 个 事件 的 监听 的 配置 工作 简单 些 。 


12.3. Hibernate 的 声明 式 安 全 机 制 


通常 ，Hibernate 应 用 程序 的 声明 式 安全 机 制 由 会 话 外 观 层 (session facade) 所 管 
理 。 现 在 ，Hibernate3 人 允许 茶 些 特定 的 行为 由 JACC 进 行 许 可 管理 ， 由 JAAS 进 行 授 
权 管 理 。 本 功能 是 一 个 建立 在 事件 框架 之 上 的 可 选 的 功能 。 


首先 ， 你 必须 要 配置 适当 的 事件 监听 器 (eventlistener) ， 来 激活 使 用 JAAS 管 理 
授权 的 功能 。 


<listener type="pre-delete" class="org.hibernate.secure.JACCPreD 
eleteEventListener"/> 

<listener type="pre-update" class="org.hibernate. secure. JACCPreu 
pdateEventListener"/> 

<listener type="pre-insert" class="org.hibernate. secure. JACCPrel 
nsertEventListener"/> 

<listener type="pre-load" class="org.hibernate.secure.JACCPreLoa 
dEventListener"/> 


注意 ， &lt;listener type="..." class="..."/&gt; 只 
是 &lt;event type="..."&gt;&lt;listener class="..."/&gt;&lt;/eventagt 


的 简写 ， 对 每 一 个 事件 类 型 都 必须 严格 的 有 一 个 监听 器 与 之 对 应 。 
接 下 来 ， 仍 然 在 hibernate,cfg.xml 文件 中 ， 绑 定 角色 的 权限 : 


<grant role="admin" entity-name="User" actions="insert, update, re 
ad"/> 
<grant role="su" entity-name="User" actions="*"/> 


这 些 角色 的 名 字 就 是 你 的 JACC provider 所 定义 的 角色 的 名 字 。 
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使 用 Hibernate 将 100 000 条 记录 播 入 到 数据 库 的 一 个 很 自然 的 做 法 可 能 是 这 样 的 


Session session = sessionFactory.openSession(); 
Transaction tx = session. beginTransaction(); 
for ( int i=0; 1<100000; i++ ) { 
Customer customer = new Customer(..... WE 
session.save(customer ); 


} 


tx.commit(); 
session.close(); 


这 上段 程序 大 概 运行 到 50000 条 记录 左右 会 失败 并 抛 出 
内 存 溢出 异常 (OutOfMemoryException) ° 这 是 因为 Hibernate 把 所 有 新 插入 的 
客户 (Customer) 实例 在 Session 级 别 的 缓存 区 进行 了 缓存 的 缘故 。 


我 们 会 在 本 章 告 诉 你 如 何 避 免 此 类 问题 。 首 先 ， 如 果 你 要 执行 批量 处 理 并 且 想 要 达 
到 一 个 理想 的 性 能 ， 那 么 使 用 JDBC 的 批量 (batching) 功能 是 至 关 重 要 。 将 JDBC 
的 批量 抓 取 数量 (batch size) 参数 设置 到 一 个 合适 值 (比如 ，10-50 之 间 ) 


hibernate.jdbc.batch_size 20 


<a class="calibre5 pcalibre pcalibre1" id="disablebatching"></a> 注 意 ,假若 你 使 用 
了 identiy 标识 符 生成 器 ,Hibernate 在 JDBC 级 别 透明 的 关闭 插入 语句 的 批量 执 


2, 


IJ 


你 也 可 能 想 在 执行 批量 处 理 时 关闭 二 级 缓存 : 


hibernate.cache.use_ second lJevel cache false 


但 是 ， 这 不 是 绝对 必须 的 ， 因 为 我 们 可 以 显 式 设置 CacheMode 来 关闭 与 二 级 缓存 
的 交互 。 


13.1. 批量 插入 (Batch inserts ) 


如 果 要 将 很 多 对 象 持 久 化 ， 你 必须 通过 经 常 的 调用 flush() 以 及 稍 后 调用 
clear() 来 控制 第 一 级 缓存 的 大 小 。 


Session session = sessionFactory.openSession(); 
Transaction tx = session. beginTransaction(); 


for ( int i=0; 1<100000; i++ ) { 
Customer customer = new Customer(..... ie 
session.save(customer ); 
if ( i % 20 == © ) { //20, same as the JDBC batch size //20, 
与 ]JDBC 批 量 设置 相同 
//flush a batch of inserts and release memory: 
// 将 本 批 插 入 的 对 象 立即 写 入 数据 库 并 释放 内 存 
session.flush(); 
session.clear(); 


} 


tx.commit(); 
session.close(); 


13.2. 批量 更 新 (Batch updates ) 


此 方法 同样 适用 于 检索 和 更 新 数据 。 此 外 ， 在 进行 会 返回 很 多 行 数据 的 查询 时 ， 你 
需要 使 用 scrol1() 方法 以 便 充 分 利用 服务 器 端 游标 所 带 来 的 好 处 。 


Session session = sessionFactory.openSession(); 
Transaction tx = session. beginTransaction(); 


ScrollableResults customers = session.getNamedQuery("GetCustomer 
Sl) 
. setCacheMode(CacheMode. IGNORE) 
.scroll(ScrollMode.FORWARD_ONLY); 
int count=0; 
while ( customers.next() ) { 
Customer customer = (Customer) customers.get(0); 
customer .updateStuff(...); 
if ( ++count % 20 == 0 ) { 
//flush a batch of updates and release memory: 
session.flush(); 
session.clear(); 


} 


tx.commit(); 
session.close(); 


13.3. StatelessSession (无 状态 session) 接 口 


作为 选择 > Hibernate 提 供 了 基于 命令 的 API， 可 以 用 detached object 的 形式 把 数据 

以 流 的 方法 加 入 到 数据 库 ， 或 从 数据 库 输 出 。 StatelessSession 没有 持久 化 上 
eee ， 也 不 提供 多 少 高 层 的 生命 周期 语义 。 特 别 是 ， 无 状态 session 不 实现 第 一 级 
cache, 也 不 和 第 二 级 缓存 ， ,或 者 查询 缓存 交互 。 它 不 实现 事务 化 写 ， 也 不 实现 脏 数 
据 检 查 。 用 stateless Session 进行 的 操作 甚至 不 级 联 到 关联 实例 。stateless session 
忽 Coleone 。 通 过 stateless session 进 行 的 操作 不 触发 Hibernate 的 事 
件 模 型 和 拦截 器 。 无 状态 session 对 数据 的 人 ， 因 为 它 没 有 第 一 级 缓存 。 
无 状态 session 是 低层 的 抽象 ， 和 低层 JDBC 相 当 接 近 


StatelessSession session = sessionFactory.openStatelessSession( ) 
/ 
Transaction tx = session.beginTransaction(); 


ScrollableResults customers = session.getNamedQuery("GetCustomer 
s") 

.Scroll(ScrollMode .FORWARD_ONLY); 
while ( customers.next() ) { 

Customer customer = (Customer) customers.get(0); 

customer .updateStuff(...); 

session.update(customer ); 


} 


tx.commit(); 
session.close(); 


注意 在 上 面 的 例子 中 ， 查 询 返 回 的 Customer 实例 立即 被 脱 管 (detach)。 它 们 与 任 
何 持久 化 上 下 文 都 没有 关系 。 


StatelessSession 接口 定义 的 insert()，update() 和 delete() 操作 是 
直接 的 数据 库 行 级 别 操作 ， 其 结果 是 立刻 执行 一 条 INSERT, UPDATE 或 DELETE 
语句 。 因 此 ， 它 们 的 语义 和 Session 接口 定义 的 save(), saveOrUpdate( ) 
和 delete() 操作 有 很 大 的 不 同 。 


13.4. DML( 数 据 操作 语言 ) 风 格 的 操作 (DML-style 
operations) 


hence manipulating (using the SQL Data Manipulation Language (DML) 
statements: INSERT , UPDATE , DELETE ) data directly in the database will not 
affect in-memory state. However, Hibernate provides methods for bulk SQL-style 
DML statement execution which are performed through the Hibernate Query 
Language (第 14 ¥ HQL: Hibernate 查 询 语 言 ). 就 像 已 经 讨论 的 那样 ， 自 动 和 透明 
的 对 象 /关系 映射 (object/relational mapping) 关注 于 管理 对 象 的 状态 。 这 就 意味 
着 对 象 的 状态 存在 于 内 存 ， 因 此 直接 操作 (使 用 SQL 

Data Manipulation Language (DML, 数 据 操作 语言 ) 语句 : INSERT 

, UPDATE 和 DELETE ) 数据 库 中 的 数据 将 不 会 影响 内 存 中 的 对 象 状态 和 对 象 数 
据 。 不过，Hibernate 提 供 通过 Hibernate 查 询 语 言 (第 14 = HQL: Hibernate 查 询 
语言 ) 来 执行 大 批 量 SQL 风 格 的 DML 语 句 的 方法 。 


UPDATE 和 DELETE 语句 的 语法 为 : 
( UPDATE | DELETE ) FROM? EntityName (WHERE where_conditions)? 有 几 
点 说 明 : 


e 在 FROM 子 尹 (from-clause) 中 ，FROM 关 键 字 是 可 选 的 


e “FROM 4) (from-clause) 中 只 能 有 一 个 实体 名 ， 它 可 以 是 别名 。 如 果实 体 
名 是 别名 ， 那 么 任何 被 引用 的 属性 都 必须 加 上 此 别名 的 前 级 ; 如 果 不 是 别名 ， 
那么 任何 有 前 缀 的 属性 引用 都 是 非法 的 。 


。 不 能 在 大 批量 HQL 语 名 中 使 用 第 14.4 节 “join 语法 的 形式 ”( 显 式 或 者 隐 式 的 都 
RAT) 。 不 过 在 WHERE 子 多 中 可 以 使 用 子 查询 。 可 以 在 where 子 尹 中 使 用 子 
查询 ， 子 查询 本 身 可 以 包含 join。 

e 整个 WHERE 子 乡 是 可 选 的 。 

举 个 例子 ， 使 用 Query.executeUpdate() 方法 执行 一 个 HQL UPDATE 78 4)(: 
(方法 命名 是 来 源 于 JDBC's PreparedStatement ,executeUpdate() ): 


Session session = sessionFactory.openSession(); 
Transaction tx = session. beginTransaction(); 


String hqlUpdate = "update Customer c set c.name = :newN 
ame where c.name = :oldName"; 

// or String hqlUpdate = "update Customer set name = :ne 
wName where name = :oldName"; 


int updatedEntities = s.createQuery( hqlUpdate ) 
.setString( "newName", newName ) 
.setString( "oldName", oldName ) 
.executeUpdate(); 

tx.commit(); 

session.close(); 


HQL UPDATE 74) > RU KABA LH KAW H 5.1.7 节 “HRA (version) (可 
ib) RAH 5.1.8 节 “timestamp (可 选 ) 属 性 值 。 这 和 EJB3 规 范 是 一 致 的 。 但 是 ， 
过 使 用 versioned update ， 你 可 以 强制 Hibernate 正 确 的 重 置 version 或 
者 timestamp 属性 值 。 这 通过 在 UPDATE 关键 字 后 面 增加 VERSIONED 关键 字 来 
实现 的 。 


(as 


Session session = sessionFactory .openSession(); 
Transaction tx = session.beginTransaction(); 
String hqlVersionedUpdate = "update versioned Customer set name 
= :newName where name = :oldName"; 
int updatedEntities = s.createQuery( hqlUpdate ) 
.setString( "newName", newName ) 
.setString( "oldName", oldName ) 
.executeUpdate(); 
tx.commit(); 
session.close(); 


注意 ， 自 定义 的 版 本 类 型 ( org.hibernate.usertype.UserVersionType ) 不 允许 
和 update versioned 7% 4) Fk A] ° 


执行 一 个 HQL DELETE ， 同 样 使 用 Query.executeUpdate() 方法 : 


Session session = sessionFactory.openSession(); 
Transaction tx = session. beginTransaction(); 


String hqlDelete = "delete Customer c where c.name = :ol 
dName"; 

// or String hqlDelete = "delete Customer where name = : 
oldName"; 


int deletedEntities = s.createQuery( hqlDelete ) 
.setString( "oldName", oldName ) 
.executeUpdate(); 

tx.commit(); 

session.close(); 


由 Query.executeUpdate() 方法 返回 的 整 型 值 表明 了 受 此 操作 影响 的 记录 数 
量 。 注意 这 个 数值 可 能 与 数据 库 中 被 〈 最 后 一 条 SQL 语句 ) BAT NT RAR? 
也 可 能 没有 。 一 个 大 批量 HQL 操 作 可 能 导致 多 条 实际 的 SQL 语 句 被 执行 ， 举 个 例 
子 ， 对 joined-subclass 映 射 方式 的 类 进行 的 此 类 操作 。 这 个 返回 值 代表 了 实际 被 语 
名 影响 了 的 记录 数量 。 在 那个 joined-subclass 的 例子 中 ， 对 一 个 子 类 的 删除 实际 上 
可 能 不 仅仅 会 删除 子 类 映射 到 的 表 而 且 会 影响 “ 根 " 表 ， 还 有 可 能 影响 与 之 有 继承 关 
系 的 joined-subclass 映 射 方式 的 子 类 的 表 。 


INSERT 语句 的 伪 码 是 : 
INSERT INTO EntityName properties_list select_statement . 要 注意 的 是 : 


e 只 支持 INSERT INTO ... SELECT ... 形 式 , 不 支持 INSERT INTO ... VALUES ... 
形式 . 


properties list 和 SQL INSERT 语句 中 

的 字段 定义 (column speficiation) 类 似 。 对 参与 继承 树 了 映射 的 实体 而 言 ， 
只 有 直接 定义 在 给 定 的 类 级 别 的 属性 才能 直接 在 properties_list 中 使 用 。 超 类 的 
属性 不 被 支持 ; 子 类 的 属性 无 意义 。 换 和 句 话 说， INSERT 天 生 不 支持 多 态 。 


e selectstatement 可 以 是 任何 合法 的 HQL 选 择 查 询 ， 不 过 要 保证 返回 类 型 必须 和 
要 插入 的 类 型 完全 匹配 。 目 前 ， 这 一 检查 是 在 查询 编译 的 时 候 进 行 的 ， 而 不 是 
把 它 交 给 数据 库 。 注 意 ， 在 Hibernate Type 问 如 果 只 是 等 价 (equivalent) 而 
非 相 等 (equal) ， 会 导致 问题 。 定 义 
为 org.hibernate.type.DateType 和 org.hibernate.type.TimestampTyp 
的 两 个 属性 可 能 会 产生 类 型 不 匹配 错误 ， 虽 然 数 据 库 级 可 能 不 加 区 分 或 者 可 以 
处 理 这 种 转换 。 


e 对 id 属性 来 说 ,insert 语 名 给 你 两 个 选择 。 你 可 以 明确 地 在 properties list 表 中 指 
定 id 属 性 (这样 它 的 值 是 从 对 应 的 select 表 达 式 中 获得 ) ， 或 者 在 
properties_list 中 省 略 它 (此 时 使 用 生成 指 ) 。 后 一 种 选择 只 有 当 使 用 在 数据 库 
中 生成 值 的 id 产生 器 时 才能 使 用 ; 如 果 是 “内 存 ” 中 计算 的 类 型 生成 器 ， 在 解析 
时 会 抛 出 一 个 异常 。 注 意 ， 为 了 说 明 这 一 问题 ， 数 据 库 产生 值 的 生成 器 
是 org.hibernate.id.SequenceGenerator 〈 和 它 的 子 类 ) ， 以 及 任 
何 org.hibernate.id.PostInsertIdentifierGenerator 接口 的 实现 。 这 
儿 最 值得 注意 的 意外 是 org.hibernate.id.TableHiLoGenerator ， 它 不 能 
在 此 使 用 ， 因 为 它 没 有 得 到 其 值 的 途径 。 


e 对 映射 为 version 或 timestamp 的 属性 来 说 ，insert 语 名 也 给 你 两 个 选 
择 ， 你 可 以 在 properties_list 表 中 指定 (此 时 其 值 从 对 应 的 select 表 达 式 中 获 
得 ) ， 或 者 在 properties_list 中 省 略 它 (此 时 ， 使 用 
在 org.hibernate.type.VersionType 中 定义 
的 seed value( 种 子 值 ) ) 。 


执行 HQL INSERT 语句 的 例子 如 下 : 


Session session = sessionFactory.openSession(); 
Transaction tx = session. beginTransaction(); 


String hqlInsert = "insert into DelinquentAccount (id, name) sel 

ect c.id, c.name from Customer c where ..."; 

int createdEntities = s.createQuery( hqlInsert ) 
.executeUpdate(); 

tx.commit(); 

session.close(); 
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Hibernate 配 备 了 一 种 非常 强大 的 查询 语言 ， 这 种 语言 看 上 去 很 像 SQL 。 
语法 +) 上 的 相似 所 类 或 ，HQL 是 非常 有 意识 的 被 设计 为 完全 面向 对 象 的 查询 ， 
可 以 理解 如 继承 、 多 态 和 关联 之 类 的 概念 。 


14.1. 大 小 写 敏 感性 问题 


除了 Java 类 与 属性 的 名 称 外 ， 查 询 语 负 对 大 小 写 并 不 敏感 。 所 以 SeLecT 4 
SELEct VAR SELECT 是 相同 的 ， 但 是 org.hibernate.eg.F00 并 不 等 价 于 
org.hibernate.eg.Foo 并 且 foo.barSet 也 不 等 价 于 foo.BARSET ° 


本 手册 中 的 HQL 关 键 字 将 使 用 小 写字 母 . 很 多 用 户 发 现 使 用 完全 大 写 的 关键 字 会 使 


查询 语句 的 可 读 性 更 强 , 但 我 们 发 现 ， 当 把 查询 语句 识 入 到 Java 语 名 中 的 时 候 使 用 
大 写 关 键 字 比较 难看 。 


14.2. from 4) 
Hibernate 中 有 最 简单 的 查询 语句 的 形式 如 下 : 


from eg ,Cat 


该 子 名 简单 的 返回 eg.cat 类 的 所 有 实例 。 通常 我 们 不 需要 使 用 类 的 全 限定 名 ， 
为 auto-import (自动 引入 ) 是 缺 省 的 情况 。 所 以 我 们 几乎 只 使 用 如 下 的 简单 
写法 : 


from Cat 


大 多 数 情况 下 , 你 需要 指定 一 个 别名 , 原因 是 你 可 能 需要 在 查询 语句 的 其 它 部 分 引用 
到 Cat 


from Cat as cat 


这 个 语句 把 别名 cat 指定 给 类 Cat 的 实例 , 这 样 我 们 就 可 以 在 随后 的 查询 中 使 用 
此 别名 了 。 关键 字 as 是 可 选 的 ， 我 们 也 可 以 这 样 写 : 


from Cat cat 
子 句 中 可 以 同时 出 现 多 个 类 , 其 查询 结果 是 产生 一 个 笛 卡 儿 积 或 产生 跨 表 的 连接 。 


from Formula, Parameter 


from Formula as form, Parameter as param 


查询 语 匈 中 别名 的 开头 部 分 小 写 被 认为 是 实践 中 的 好 习惯 ， 这 样 做 与 Java 变 量 的 命 
名 标准 保持 了 一 致 (比如 ， domesticCat )。 


14.3. 关联 (Association) 与 连接 (Join) 


我 们 也 可 以 为 相关 联 的 实体 甚至 是 对 一 个 集合 中 的 全 部 元 素 指定 一 个 别名 , 这 时 要 
使 用 关键 字 join 。 


from Cat as cat 
inner join cat.mate as mate 
left outer join cat.kittens as kitten 


from Cat as cat left join cat.mate.kittens as kittens 


from Formula form full join form.parameter param 


受 支持 的 连接 类 型 是 从 ANSI SQL 中 借鉴 来 的 。 
e inner join (内 连接 ) 
e left outer join ( 左 外 连接 ) 
e right outer join ( 右 外 连接 ) 
e full join (全 连接 ， 并 不 常用 ) 


7&4) inner join , left outer join 以 及 right outer join 可 以 简写 。 


from Cat as cat 
Join cat.mate as mate 
left join cat.kittens as kitten 


过 HQL 的 with 关键 字 ， 你 可 以 提供 额外 的 join 条 件 。 


from Cat as cat 
left join cat.kittens as kitten 
with kitten.bodyWeight > 10.0 


还 有 ， 一 个 "fetch" 连 接 允 许 仅 仅 使 用 一 个 选择 语句 就 将 相关 联 的 对 象 或 一 组 值 的 集 
合 随 着 他 们 的 父 对 象 的 初始 化 而 被 初始 化 ， 这 种 方法 在 使 用 到 集合 的 情况 下 尤其 有 
用 ， 对 于 关联 和 集合 来 说 ， 它 有 效 的 代替 了 映射 文件 中 的 外 联接 与 延迟 声明 (lazy 
declarations) . 查看 第 19.1 节 “ 抓 取 策 略 (Fetching strategies) ”以 获得 等 多 的 信 


Rs ° 


from Cat as cat 
inner join fetch cat.mate 
left join fetch cat.kittens 


一 个 fetch 连 接 通 常 不 需要 被 指定 别名 , 因为 相关 联 的 对 象 不 应 当 被 用 在 where F 
a (或 其 它 任何 子 甸 ) 中 。 同 时 ， 相 关联 的 对 象 并 不 在 查询 的 结果 中 直接 返回 ， 但 可 
通过 他 们 的 父 对 象 来 访问 到 他 们 。 


from Cat as cat 
inner join fetch cat.mate 
left join fetch cat.kittens child 
left join fetch child.kittens 


假若 使 用 iterate() 来 调用 查询 ， 请 注意 fetch 构造 是 不 能 使 用 的 ( 

可 以 使 用 )。 fetch 也 不 应 该 与 setMaxResults() 或 setFirstResult() # 

用 ， 这 是 因为 这 些 操作 是 基于 结果 集 的 ， 而 在 预先 抓 取 集合 类 时 可 能 包含 重复 的 数 

据 ， 也 就 是 说 无 法 预先 知道 精确 的 行 数 。 fetch 还 不 能 与 独立 的 with 条 件 一 

使 用 。 通 过 在 一 次 查询 中 fetch 多 个 集合 ， 可 以 制造 出 秒 ;卡尔 各 ， 因 此 请 多 加 注意 

对 bag 映 射 来 说 ， 同 时 join fetch 多 个 集合 角色 可 能 在 东 些 情况 下 给 $ 出 并 非 预 期 的 

果 ， 也 请 小 心 。 最 后 注意 ， 使 用 full join sie 与 right join fetch 是 没 
意义 的 。 


如 果 你 使 用 属性 级 别 的 延迟 获取 (lazy fetching) (这 是 通过 重新 编写 字 节 码 实 现 
的 ) ， 可 以 使 用 fetch all properties 来 强制 Hibernate 立 即 取得 那些 原本 需 
要 延迟 加 载 的 属性 《在 第 一 个 查询 中 ) 。 


from Document fetch all properties order by name 


from Document doc fetch all properties where lower(doc.name) lik 
e '%cats%' 


14.4. join 语法 的 形式 


HQL 支 持 两 种 关联 join 的 形式 : implicit( 隐 式 ) 与 explicit (ZA) 。 


上 一 节 中 给 出 的 查询 都 是 使 用 explicit( 显 式 ) 形式 的 ， 其 中 form 子 名 中 明确 给 
了 join 关 键 字 。 这 是 建议 使 用 的 方式 。 


implicit (BA) 形式 不 使 用 join 关 键 字 。 关 联 使 用 "点 号 "来 进行 “ 引 
”o implicit join 可 以 在 任何 HQL 子 名 中 出 现 . implicit join 在 最 终 的 SQL 语 
4) P inner join 的 方式 出 现 。 


from Cat as cat where cat.mate.name like '%s%' 


14.5. select 7 4 
select 子 句 选择 将 哪些 对 象 与 属性 返 回 到 查询 结果 集中 . 考虑 如 下 情况 : 


select mate 
from Cat as cat 
inner join cat.mate as mate 


该 语句 将 选择 mate sofother cat sc (其 他 猫 的 配偶 ) 实际 上 , 你 可 以 更 简洁 
的 用 以 下 的 查询 语句 表达 相同 的 含义 : 


select cat.mate from Cat cat 


查询 语 多 可 以 返回 值 为 任何 类 型 的 属性 ， 包 括 返 回 类 型 为 某 种 组 件 (Component) 的 
属性 : 


select cat.name from DomesticCat cat 
where cat.name like 'fri%' 


select cust.name.firstName from Customer as cust 


查询 语句 可 以 返回 多 个 对 但 和 (或 ) 属性 ， 存 放 在 Object[] 队列 中 ， 


select mother, offspr, mate.name 
from DomesticCat as mother 
inner join mother.mate as mate 
left outer join mother.kittens as offspr 


或 存放 在 一 个 List TRF, 


select new list(mother, offspr, mate.name) 
from DomesticCat as mother 

inner join mother.mate as mate 

left outer join mother.kittens as offspr 


也 可 能 直接 返回 一 个 实际 的 类 型 安全 的 Java 对 象 ， 


select new Family(mother, mate, offspr) 
from DomesticCat as mother 

join mother.mate as mate 

left join mother.kittens as offspr 


假设 类 Family 有 一 个 合适 的 构造 函数 . 
你 可 以 使 用 关键 字 as 给 “被 选择 了 的 表达 式 " 指 派别 名 : 


select max(bodyWeight) as max, min(bodyweight) as min, count(*) 
as n 
from Cat cat 


这 种 做 法 在 与 子 铭 select new map 一 起 使 用 时 最 有 用 : 


select new map( max(bodyWeight) as max, min(bodyWeight) as min, 
count(*) as n ) 
from Cat cat 


该 查询 返回 了 一 个 Map 的 对 象 ， 内 容 是 别名 与 被 选择 的 值 组 成 的 名 - 值 映射 。 


14.6. 采集 函数 
HQL 查 询 其 至 可 以 返回 作用 于 属性 之 上 的 聚集 函数 的 计算 结果 : 


select avg(cat.weight), sum(cat.weight), max(cat.weight), count( 
cat) 


from Cat cat 


受 支 持 的 聚集 函数 如 下 


e avg(...), sum(...), min(...), max(...) 


e count(*) 
e count(...), count(distinct ...), count(all...) 


AR Oy AAT a PAE RARE. E AA A t ATE SALAA : 


select cat.weight + sum(kitten.weight) 
from Cat cat 

join cat.kittens kitten 
group by cat.id, cat.weight 


select firstName||' '||initial||' '||upper(lastName) from Person 


关键 字 distinct 与 all 也 可 以 使 用 ， 它 们 具有 与 SQL 相同 的 语义 . 


select distinct cat.name from Cat cat 


select count(distinct cat.name), count(cat) from Cat cat 


14.7. 多 态 查询 
一 个 如 下 的 查询 语句 : 


from Cat as cat 


不 仅 返 回 Cat 类 的 实例 , 也 同时 返回 子 类 Domesticcat 的 实例 . Hibernate 可 以 
在 from 子 句 中 指定 任何 Java 类 或 接口 . 查询 会 返回 继承 了 该 类 的 所 有 持久 化 子 
类 的 实例 或 返回 声明 了 该 接口 的 所 有 持久 化 类 的 实例 。 下 面 的 查询 语句 返回 所 有 的 
被 持久 化 的 对 象 : 


from java.lang.Object 0 
接口 Named 可 能 被 各 种 各 样 的 持久 化 类 声明 : 


from Named n, Named m where n.name = m.name 


注意 ， 最 后 的 两 个 查询 将 需要 超过 一 个 的 SQL SELECT .这 表明 order by FY 没 
有 对 整个 结果 集 进行 正确 的 排序 . (这 也 说 明 你 不 能 对 这 样 的 查询 使 
用 Query.scroll() 方法 .) 


14.8. where f 4J 


where 子 句 允许 你 将 返回 的 实例 列表 的 范围 缩 果 没 有 指定 别名 ， 你 可 以 使 用 
属性 名 来 直接 引用 属性 : 


from Cat where name='Fritz' 


如 果 指 派 了 别名 ， 需 要 使 用 完整 的 属性 名 : 


from Cat as cat where cat.name='Fritz' 


返回 名 为 (属性 name 等 于 ) 'Fritz' 的 cat 类 的 实例 。 


select foo 
from Foo foo, Bar bar 
where foo.startDate = bar.date 


将 返回 所 有 满足 下 面条 件 的 Foo 类 的 实例 : 存在 如 下 的 bar 的 一 个 实例 ， 
其 date 属性 等 于 Foo 的 startDate 属性 。 复 合 路 径 表 达 式 使 得 where $4 
非常 的 强大 ， 考 虑 如 下 情况 : 


from Cat cat where cat.mate.name is not null 


该 查询 将 被 翻译 成 为 一 个 含有 表 连 接 (内 连接 ) 的 SQL 查询 。 如 果 你 打算 写 像 这 样 
的 查询 语句 


from Foo foo 
where foo.bar.baz.customer.address.city is not null 


在 SQL 中 ， 你 为 达 此 目的 将 需要 进行 一 个 四 表 连 接 的 查询 。 
= 运算 符 不 仅 可 以 被 用 来 比较 属性 的 值 ， 也 可 以 用 来 比较 实例 : 


from Cat cat, Cat rival where cat.mate = rival.mate 
select cat, mate 


from Cat cat, Cat mate 
where cat.mate = mate 


特殊 属性 (小 写 ) id 可 以 用 来 表示 一 个 对 象 的 唯一 的 标识 符 。 (你 也 可 以 使 用 该 
对 象 的 属性 名 。 ) 


from Cat as cat where cat.id = 123 


from Cat as cat where cat.mate.id = 69 


第 二 个 查询 是 有 效 的 。 此 时 不 需要 进行 表 连 接 ! 


同样 也 可 以 使 用 复合 标识 符 。 比 如 Person 类 有 一 个 复合 标识 符 ， 它 
由 country 属性 与 medicareNumber 属性 组 成 。 


from bank.Person person 
where person.id.country = 'AU' 
and person.id.medicareNumber = 123456 


from bank.Account account 
where account.owner.id.country = 'AU' 
and account.owner.id.medicareNumber = 123456 


第 二 个 查询 也 不 需要 进行 表 连接 。 


同样 的 ， 特 殊 属 性 class 在 进行 多 态 持 久 化 的 情况 下 被 用 来 存 取 一 个 实例 的 鉴别 
值 (discriminator value) 。 一 个 识 入 到 where 子 名 中 的 Java 类 的 名 字 将 被 转换 为 
该 类 的 鉴别 值 。 


from Cat cat where cat.class = DomesticCat 


你 也 可 以 声明 一 个 属性 的 类 型 是 组 件 或 者 复合 用 户 类 型 (以 及 由 组 件 构 成 的 组 件 等 
F) 。 永 远 不 要 尝试 使 用 以 组 件 类 型 来 结尾 的 路 径 表 达 式 (path-expression) (4 
此 相反 ， 你 应 当 使 用 组 件 的 一 个 属性 来 结尾 ) 。 举例 来 说 ， 如果 store.owner & 
有 一 个 包含 了 组 件 的 实体 address 


store.owner.address.city // 正确 
store.owner.address // 错误 


一 个 "任意 "类 型 有 两 个 特殊 的 属性 id 和 class ,来 允许 我 们 按照 下 面 的 方式 表达 
一 个 连接 ( AuditLog.item 有 是 一 个 属性 ， 该 属性 被 映射 为 &lt;any&gt; ) ° 


from AuditLog log, Payment payment 
where log.item.class = 'Payment' and log.item.id = payment.id 


注意 ， 在 上 面 的 查询 与 名 中 ， log.item.class 和 payment.class 将 涉及 到 完 
全 不 同 的 数据 库 中 的 列 。 


14.9. 表达 式 


在 where 子 句 中 允许 使 用 的 表达 式 包 括 大 多 数 你 可 以 在 SQL 使 用 的 表达 式 种 类 : 
。 数学 运算 符 +，-，*，/ 
。 二 进 制 比较 运算 符 =, &gt:i=, &lt:=, &lti&gt;, !=, like 
e 逻辑 运算 符 and，or，nmnot 


e in, not in, between , is null , is not null , is empty , 
is not empty , member of and not member of 


e "简单 的 " case, case ... when ... then... else ... end ,和 "搜索 " 
case, case when ... then... else ... end 
o FH BRR ...[|... or concat(...,...) 


e current_date() , current_time() , current_timestamp() 


e second(...) , minute(...) , hour(...) , day(...) ,， month(...),, 
year(...) , 


e EJB-QL 3.0 定 义 的 任何 函数 或 操 
作 : substring(), trim(), lower(), upper(), length(), locate(), a 


e coalesce() 和 nullif() 
e。 str() 把 数字 或 者 时 间 值 转换 为 可 读 的 字符 串 


e cast(... as...) ,其 第 二 个 参数 是 某 Hibernate 类 型 的 名 字 ， 以 
及 extract(... from...) ， 只 要 ANSI cast() 和 extract() 被 底层 
数据 库 支 持 


e HQL index() 函数 ， 作 用 于 join 的 有 序 集合 的 别名 。 
e HQL 兄 数 ， 把 集合 作为 参 


数 : size(), minelement(), maxelement(), minindex(), maxindex() , 
还 有 特别 的 elements() 和 indices 函数 ， 可 以 与 数量 词 加 以 限 


人 > 


Æ : some, all, exists, any, in ° 


o 任何 数据 库 支 持 的 SQL 标量 函数 ， 比 如 sign() , trunc() , rtrim() , 
sin() 


o JDBC 风 格 的 参数 传 入 2 
e 命名 参数 name , :start_date , :x1 


e SQL 直接 常量 'foo' , 69, 6.66E+2 , '1970-01-01 10:00:01.0' 


e Java public static final 类 型 的 常量 eg.Color. TABBY 


关键 字 in 与 between 可 按 如 下 方法 使 用 : 


from DomesticCat cat where cat.name between 'A' and 'B' 


from DomesticCat cat where cat.name in ( 'Foo', 'Bar', 'Baz' ) 


而 且 和 否定 的 格式 也 可 以 如 下 书写 : 


from DomesticCat cat where cat.name not between 'A' and 'B' 


from DomesticCat cat where cat.name not in ( 'Foo', 'Bar', 'Baz' 


) 


同样 , 子 句 is null 与 is not null 可 以 被 用 来 测试 空 值 (null). 


在 Hibernate 配 置 文件 中 声明 HQL“ 查 询 替 代 〈query substitutions) "之 后 ， 布 尔 表 
XA (Booleans) 可 以 在 其 他 表达 式 中 轻松 的 使 用 : 


<property name="hibernate.query.substitutions">true 1, false 0</ 
property> 


系统 将 该 HQL 转 换 为 SQL 语 句 时， 该 设置 表明 将 用 字符 1 和 o 来 取代 关键 
字 true 和 false : 


from Cat cat where cat.alive = true 


你 可 以 用 特殊 属性 size ,或 是 特殊 函数 size() 测试 一 个 集合 的 大 小 。 


from Cat cat where cat.kittens.size > 0 


from Cat cat where size(cat.kittens) > 0 


对 于 索引 了 (有 序 ) 的 集合 ， 你 可 以 使 用 minindex 与 maxindex 函数 来 引用 到 
最 小 与 最 大 的 索引 序数 。 同 理 ， 你 可 以 使 用 minelement 4 maxelement 函数 
来 引用 到 一 个 基本 数据 类 型 的 集合 中 最 小 与 最 大 的 元 素 。 


from Calendar cal where maxelement(cal.holidays) > current_date 
from Order order where maxindex(order.items) > 100 


from Order order where minelement(order.items) > 10000 


在 传递 一 个 集合 的 索引 集 或 者 是 元 素 集 ( elements 与 indices 函数 ) 或 者 传递 一 
个 子 查询 的 结果 的 时 候 ， 可 以 使 用 SQL 函数 any, some, all, exists, in 


select mother from Cat as mother, Cat as kit 
where kit in elements(foo.kittens) 


select p from NameList list, Person p 
where p.name = some elements(list.names) 


from Cat cat where exists elements(cat.kittens) 
from Player p where 3 > all elements(p.scores) 


from Show show where 'fizard' in indices(show.acts) 


注意 ， 在 Hibernate3 种 ， 这 些 结构 变量 - size , elements , indices , 
minindex , maxindex , minelement , maxelement -只 能 在 where 子 名 中 使 
HE 

一 个 被 索引 过 的 〈 有 序 的 ) 集合 的 元 素 (arrays, lists, maps) 可 以 在 其 他 索引 中 被 引 
用 (只 能 在 where 子 名 中) : 


from Order order where order.items[0].id = 1234 


select person from Person person, Calendar calendar 
where calendar.holidays['national day'] = person.birthDay 
and person.nationality.calendar = calendar 


select item from Item item, Order order 
where order.items[ order.deliveredItemIndices[0] ] = item and or 
der.id = 11 


select item from Item item, Order order 
where order.items[ maxindex(order.items) ] = item and order.id = 
11 


在 [] 中 的 表达 式 甚至 可 以 是 一 个 算数 表达 式 。 


select item from Item item, Order order 


where order.items[ size(order.items) - 1 ] item 


对 于 一 个 一 对 多 的 关联 (one-to-many association) 或 是 值 的 集合 中 的 元 素 ，HQL 
也 提供 内 建 的 index() Ba? 


select item, index(item) from Order order 
join order.items item 
where index(item) < 5 


如 果 族 层 数 据 库 支 持 标量 的 SQL 函数 ， 它 们 也 可 以 被 使 用 


from DomesticCat cat where upper(cat.name) like 'FRI%' 


如 果 你 还 不 能 对 所 有 的 这 些 深信 不 疑 ， 想 想 下 面 的 查询 。 如 果 使 用 SQL， 语 名 长 度 
会 增长 多 少 ， 可 读 性 会 下 降 多 少 : 


select cust 
from Product prod, 
Store store 
inner join store.customers cust 
where prod.name = 'widget' 
and store.location.name in ( 'Melbourne', 'Sydney' ) 
and prod = all elements(cust.currentOrder.lineItems) 


提示 : 会 像 如 下 的 语句 


SELECT cust.name, cust.address, cust.phone, cust.id, cust.curren 
t_order 
FROM customers cust, 
stores store, 
locations loc, 
store_customers SC, 
product prod 
WHERE prod.name = 'widget' 
AND store.loc_id = loc.id 
AND loc.name IN ( 'Melbourne', 'Sydney' ) 
AND sc.store_id = store.id 
AND sc.cust_id = cust.id 
AND prod.id = ALL( 
SELECT item.prod_id 
FROM line_items item, orders o 
WHERE item.order_id = o.id 
AND cust.current_order = o.id 


14.10. order byt 4 


查询 返回 的 列表 (list) 可 以 按照 一 个 返回 的 类 或 组 件 (components) 中 的 任何 属性 
(property) 进行 排序 : 


from DomesticCat cat 
order by cat.name asc, cat.weight desc, cat.birthdate 


可 选 的 asc 或 desc 关键 字 指 明了 按照 升序 或 降序 进行 排序 . 


14.11. group by 4 


一 个 返回 聚集 值 (aggregate values) 的 查询 可 以 按照 一 个 返回 的 类 或 组 件 
(components) 中 的 任何 属性 (property) 进行 分 组 : 


select cat.color, sum(cat.weight), count(cat) 
from Cat cat 
group by cat.color 


select foo.id, avg(name), max(name) 
from Foo foo join foo.names name 
group by foo.id 


having Faye EWA A. 


select cat.color, sum(cat.weight), count(cat) 

from Cat cat 

group by cat.color 

having cat.color in (eg.Color.TABBY, eg.Color.BLACK) 


eo RJR JE GI RIE JE RAF 9 TE (AA ho FEE MySQL ¥ 1% 771) > SQLAI BAA RK BH 
数 也 可 以 出 现在 having 与 order by +4) ¥ ° 


select cat 
from Cat cat 
join cat.kittens kitten 
group by cat.id, cat.name, cat.other, cat.properties 
having avg(kitten.weight) > 100 
order by count(kitten) asc, sum(kitten.weight) desc 


注意 group by +44 order by FAPMARALSHARARA (arithmetic 
expressions) . 也 要 注意 Hibernate 目 前 不 会 扩展 group 的 实体 ,因此 你 不 能 

写 group by cat ,除非 cat 的 所 有 属性 都 不 是 聚集 的 (non-aggregated)。 你 必须 
明确 的 列 出 所 有 的 非 聚 集 属性 。 


14.12. 子 查询 


对 于 支持 子 查 询 的 数据 库 ，Hibernate 支 持 在 查询 中 使 用 子 查 询 。 一 个 子 查询 必须 被 
圆 括 号 包围 起 来 (经常 是 SQL 聚集 函数 的 圆 括号 ) 。 甚至 相互 关联 的 子 查询 (引用 
到 外 部 查询 中 的 别名 的 子 查询 ) 也 是 允许 的 。 


from Cat as fatcat 
where fatcat.weight > ( 

select avg(cat.weight) from DomesticCat cat 
) 


from DomesticCat as cat 
where cat.name = some ( 

select name.nickName from Name as name 
) 


from Cat as cat 
where not exists ( 

from Cat as mate where mate.mate = cat 
) 


from DomesticCat as cat 
where cat.name not in ( 

select name.nickName from Name as name 
) 


select cat.id, (select max(kit.weight) from cat.kitten kit) 
from Cat as cat 
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在 select 列 表 中 包含 一 个 表达 式 以 上 的 子 查询 ， 你 可 以 使 用 一 个 元 组 构造 符 (tuple 
constructors ) 


from Cat as cat 
where not ( cat.name, cat.color ) in ( 

select cat.name, cat.color from DomesticCat cat 
) 


注意 在 某 些 数据 库 中 (不 包括 Oracle 与 HSQL ) ， 你 也 可 以 在 其 他 语 境 中 使 用 元 组 
构造 符 ， 比如 查询 用 户 类 型 的 组 件 与 组 合 : 


from Person where name = ('Gavin', 'A', 'King') 


该 查询 等 价 于 更 复杂 的 : 


from Person where name.first = 'Gavin' and name.initial = 'A' an 
d name.last = 'King') 


有 两 个 很 好 的 理由 使 你 不 应 当 作 这 样 的 事情 : 首先 ， 它 不 完全 适用 于 各 个 数据 库 平 
台 ; 其 次 ， 查 询 现 在 依赖 于 映射 文件 中 属性 的 顺序 。 


14.13. HQL 示 例 


Hibernate 查 询 可 以 非常 的 强大 与 复杂 。 实 际 上 ，Hibernate 的 一 个 主要 卖点 就 是 查 
询 语 句 的 威力 。 这 里 有 一 些 例 子 ， 它 们 与 我 在 最 近 的 一 个 项 目 中 使 用 的 查询 非常 相 


似 。 注 意 你 能 用 到 的 大 多 数 查 询 比 这 些 要 简单 的 多 | 


下 本 A nisi 在 给 
下 ， 返 回 订单 的 id， 条 目的 数量 和 总 价值 ， 返 回 值 按照 总 价 


给 最 小 总 价值 的 情况 
ee 5 果 进 行 排序 。 。 为 


了 决定 价格 ， 查询 使 用 了 当前 目录 。 。 作 为 转换 5 果 的 SQ[ 查询 ， 使 用 了 ORDER , 


ORDER_LINE ， PRODUCT ，CATALOG 和 PRICE 库 表 。 


select order.id, sum(price.amount), count(item) 
from Order as order 
join order.lineItems as item 
join item.product as product, 
Catalog as catalog 
join catalog.prices as price 
where order.paid = false 
and order.customer = :customer 
and price.product = product 
and catalog.effectiveDate < sysdate 
and catalog.effectiveDate >= all ( 
select cat.effectiveDate 
from Catalog as cat 
where cat.effectiveDate < sysdate 
) 
group by order 
having sum(price.amount) > :minAmount 
order by sum(price.amount) desc 


这 简直 是 一 个 怪物 ! 实际 上 ， 在 现实 生活 中 ， 我 并 不 热 袁 于 
语句 看 起 来 更 像 这 个 


select order.id, sum(price.amount), count(item) 
from Order as order 

join order.lineItems as item 

join item.product as product, 

Catalog as catalog 

join catalog.prices as price 
where order.paid = false 


and order.customer = :customer 
and price.product = product 
and catalog = :currentCatalog 


group by order 
having sum(price.amount) > :minAmount 
order by sum(price.amount) desc 


子 查询 ， 所 以 我 的 查询 


下 面 一 个 查询 计算 每 一 种 状态 下 的 支付 的 数目 ， 除 去 所 有 处 
于 AWAITING_APPROVAL 状态 的 支付 ， 因 为 在 该 状态 下 当前 的 用 户 作 出 了 状态 的 
最 新 改变 。 该 查询 被 转换 成 含有 两 个 内 连接 以 及 一 个 相关 联 的 子 选 择 的 SQL 查询 ， 
该 查询 使 用 了 表 PAYMENT , PAYMENT_STATUS 以 及 

PAYMENT_STATUS_CHANGE 。 


select count(payment), status.name 
from Payment as payment 
join payment.currentStatus as status 
join payment.statusChanges as statusChange 
where payment.status.name <> PaymentStatus.AWAITING_APPROVAL 
or ( 
statusChange.timeStamp = ( 
select max(change.timeStamp) 
from PaymentStatusChange change 
where change.payment = payment 


) 


and statusChange.user <> :currentUser 
) 
group by status.name, status.sortOrder 
order by status.sortOrder 


如 果 我 把 statusChanges 实例 集 映 射 为 一 个 列表 (list) 而 不 是 一 个 集合 〈set) , 
书写 查询 语句 将 更 加 简单 . 


select count(payment), status.name 
from Payment as payment 
join payment.currentStatus as status 
where payment.status.name <> PaymentStatus.AWAITING_APPROVAL 
or payment.statusChanges[ maxIndex(payment.statusChanges) ]. 
user <> :currentUser 
group by status.name, status.sortOrder 
order by status.sortOrder 


下 面 一 个 查询 使 用 了 MS SQL Server) isNull() 函数 用 以 返回 当前 用 户 所 属 组 
织 的 组 织 帐 号 及 组 织 未 支付 的 账 。 它 被 转换 成 一 个 对 表 ACCOUNT , PAYMENT , 
PAYMENT_STATUS , ACCOUNT_TYPE , ORGANIZATION YAR ORG_USER 进行 的 
三 个 内 连接 ， 一 个 外 连接 和 一 个 子 选择 的 SQL 查询 。 


select account, payment 
from Account as account 

left outer join account.payments as payment 
where :currentUser in elements(account.holder.users) 

and PaymentStatus.UNPAID = isNull(payment.currentStatus.name 
, PaymentStatus.UNPAID) 
order by account.type.sortOrder, account.accountNumber, payment. 
dueDate 


对 于 一 些 数据 库 ， 我 们 需要 弃 用 (相关 的 ) 子 选择 。 


select account, payment 
from Account as account 

join account.holder.users as user 

left outer join account.payments as payment 
where :currentUser = user 

and PaymentStatus.UNPAID = isNull(payment.currentStatus.name 
, PaymentStatus.UNPAID) 
order by account.type.sortOrder, account.accountNumber, payment. 
dueDate 


14.14. 批量 的 UPDATE 和 DELETE 


HQL 现 在 支持 update , delete 和 insert ... select ... 语句 . 查阅 第 
13.4 节 “DML( 数 据 操作 语言 ) 风 格 的 操作 (DML-style operations)” 以 获得 更 多 信息 。 


14.15. 小 技巧 & DZT] 
你 可 以 统计 查询 结果 的 数目 而 不 必 实 际 的 返回 他 们 : 


( (Integer) session.iterate("select count(*) from ....").next() 
).intValue() 


若 想 根据 一 个 集合 的 大 小 来 进行 排序 ， 可 以 使 用 如 下 的 语句 : 


select usr.id, usr.name 
from User as usr 
left join usr.messages as msg 
group by usr.id, usr.name 
order by count(msg) 


如 果 你 的 数据 库 支 持 子 选 择 ， 你 可 以 在 你 的 查询 的 Where 子 多 中 为 选择 的 大 小 
(selection size) 指定 一 个 条 件 : 


from User usr where size(usr.messages) >= 1 


如 果 你 的 数据 库 不 支持 子 选择 语句 ， 使 用 下 面 的 查询 : 


select usr.id, usr.name 
from User usr.name 

Join usr.messages msg 
group by usr.id, usr.name 
having count(msg) >= 1 


因为 内 连接 (inner join) 的 原因 ， 这 个 解决 方案 不 能 返回 含有 零 个 信息 的 User 
类 的 实例 , 所 以 这 种 情况 下 使 用 下 面 的 格式 将 是 有 帮助 的 : 


select usr.id, usr.name 
from User as usr 
left join usr.messages as msg 
group by usr.id, usr.name 
having count(msg) = 0 


JavaBean 的 属性 可 以 被 绑 定 到 一 个 命名 查询 (named query) 的 参数 上 : 


Query q = s.createQuery("from foo Foo as foo where foo.name=:nam 
e and foo.size=:size"); 

q.setProperties(fooBean); // fooBean& 27% #getName( ) 与 getSize() 
List foos = q.list(); 


2, 


通过 将 接口 Query 与 一 个 过 滤器 (filter) 一 起 使 用 ， 集 合 (Collections) 是 可 以 
分 页 的 : 


N 


Query q = s.createFilter( collection, "" ); // 一 个 简单 的 过 滤器 
q.setMaxResults(PAGE_SIZE); 

q.setFirstResult(PAGE_SIZE * pageNumber); 

List page = q.list(); 


通过 使 用 查询 过 滤器 (query filter) 可 以 将 集合 (Collection) 的 原 素 分 组 或 排序 : 


Collection orderedCollection = s.filter( collection, "order by t 
his.amount" ); 

Collection counts = s.filter( collection, "select this.type, cou 
nt(this) group by this.type" ); 


不 用 通过 初始 化 ， 你 就 可 以 知道 一 个 集合 (Collection ) 的 大 小 : 


( (Integer) session.iterate("select count(*) from ....").next() 
).intValue(); 


第 15 章 条 件 查询 (Criteria Queries) 
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15.1. 创建 一 个 Criteria 实例 

15.2. 限制 结果 集 内 容 

15.3. 结果 集 排 序 

15.4. 关联 

15.5. 动态 关联 抓 取 

15.6. 查询 示例 

15.7. 4% (Projections) ` R&A (aggregation) 和 分 组 (grouping) 
15.8. 离线 (detached) 查 询 和 子 查询 

15.9. 根据 自然 标识 查询 (Queries by natural identifier) 


具有 一 个 直观 的 、 可 扩展 的 条 件 查 询 API 是 Hibernate 的 特色 。 


15.1. 创建 一 个 Criteria 实例 


org.hibernate.Criteria 接口 表示 特定 持久 类 的 一 个 查询 。 Session 是 
Criteria 实例 的 工厂 。 


Criteria crit = sess.createCriteria(Cat.class); 
crit.setMaxResults(50); 
List cats = crite list): 


15.2. 限制 结果 集 内容 


一 个 单独 的 查询 条 件 是 org.hibernate.criterion.Criterion 接口 的 一 个 实 
例 。 org.hibernate.criterion.Restrictions 类 定义 了 获得 某 些 内 
置 Criterion 类 型 的 工厂 方法 。 


List cats = sess.createCriteria(Cat.class) 
.add( Restrictions.like("name", "Fritz%") ) 
.add( Restrictions.between("weight", minWeight, maxWeight) ) 
LLS EIC 


约束 可 以 按 逻 辑 分 组 。 


List cats = sess.createCriteria(Cat.class) 
.add( Restrictions.like("name", "Fritz%") ) 
.add( Restrictions.or( 
Restrictions.eq( "age", new Integer(0) ), 
Restrictions.isNull("age") 


) ) 
.list(); 


List cats = sess.createCriteria(Cat.class) 
.add( Restrictions.in( "name", new String[] { "Fritz", "Izi" 
oe D) 
.add( Restrictions.disjunction() 
.add( Restrictions.isNull("age") ) 
.add( Restrictions.eq("age", new Integer(0) ) ) 
.add( Restrictions.eq("age", new Integer(1) ) ) 
.add( Restrictions.eq("age", new Integer(2) ) ) 


Hibernate 提 供 了 相当 多 的 内 置 criterion 类 型 ( Restrictions 子 类 ), 但 是 尤其 有 用 
的 是 可 以 允许 你 直接 使 用 SQL 。 


List cats = sess.createCriteria(Cat.class) 

.add( Restrictions.sqlRestriction("lower({alias}.name) like 
lower(?)", "Fritz%", Hibernate.STRING) ) 

.list(); 


{alias} 占 位 符 应 当 被 替换 为 被 查询 实体 的 列 别名 。 


Property 实例 是 获得 一 个 条 件 的 另外 一 种 途径 。 你 可 以 通过 调 
用 Property.forName() 创建 一 个 Property 。 


Property age = Property.forName("age"); 
List cats = sess.createCriteria(Cat.class) 
.add( Restrictions.disjunction() 
.add( age.isNull() ) 
.add( age.eq( new Integer(0) ) ) 
.add( age.eq( new Integer(1) ) ) 
.add( age.eq( new Integer(2) ) ) 
) ) 
.add( Property.forName("name").in( new String[] { "Fritz", " 
TZAN "pk" } ) ) 
ATSE); 


15.3. 结果 集 排序 
你 可 以 使 用 org,hibernate.criterion.0rder 来 为 查询 结果 排序 。 


List cats = sess.createCriteria(Cat.class) 
.add( Restrictions.like("name", "F%") 
.addOrder( Order.asc("name") ) 
.addOrder( Order.desc("age") ) 
.setMaxResults(50) 

ESE 


List cats = sess.createCriteria(Cat.class) 
.add( Property.forName("name").like("F%") ) 
.addOrder( Property.forName("name").asc() ) 
.addOrder( Property.forName("age").desc() ) 
.setMaxResults(50) 

SUSE) s 


15.4. 关联 
你 可 以 使 用 createCriteria() 非常 容易 的 在 互相 关联 的 实体 问 建 立 约束 。 


List cats = sess.createCriteria(Cat.class) 
.add( Restrictions.like("name", "F%") ) 
.createCriteria("kittens") 

.add( Restrictions.like("name", "F%") ) 
eS EE) 


注意 第 二 个 createCriteria() 返回 一 个 新 的 Criteria 实例 ， 该 实例 引 
用 kittens 集合 中 的 元 素 。 


接 下 来 ， 替 换 形态 在 茶 些 情况 下 也 是 很 有 用 的 。 


List cats = sess.createCriteria(Cat.class) 
.createAlias("kittens", "kt") 
.createAlias("mate", "mt") 
.add( Restrictions.eqProperty("kt.name", "mt.name") ) 
TSE Os 


( createAlias() 并 不 创建 一 个 新 的 Criteria 实例 。) 


Cat 实例 所 保存 的 之 前 两 次 查询 所 返回 的 kittens 集 合 是 没有 被 条 件 预 过 滤 的 。 如 
果 你 希望 只 获得 符合 条 件 的 kittens ， 你 必须 使 用 ResultTransformer 。 


List cats = sess.createCriteria(Cat.class) 
.createCriteria("kittens", "kt") 

.add( Restrictions.eq("name", "F%") ) 
.setResultTransformer(Criteria.ALIAS TO _ENTITY_MAP) 
PIS EO 

Iterator iter = cats.iterator(); 

while ( iter.hasNext() ) { 
Map map = (Map) iter.next(); 
Cat cat = (Cat) map.get(Criteria.ROOT_ALIAS); 
Cat kitten = (Cat) map.get("kt"); 


15.5. 动态 关联 抓 取 
你 可 以 使 用 setFetchMode() 在 运行 时 定义 动态 关联 抓 取 的 语义 。 


List cats = sess.createCriteria(Cat.class) 
.add( Restrictions.like("name", "Fritz%") ) 
.setFetchMode("mate", FetchMode.EAGER) 
.setFetchMode("kittens", FetchMode.EAGER) 
.list(); 


这 个 查询 可 以 通过 外 连接 抓 取 mate 和 kittens 。 查看 第 19.1 节 “ 抓 取 汞 略 
(Fetching strategies) "可 以 获得 更 多 信息 。 


15.6. 查询 示例 


org.hibernate.criterion.Example 类 允许 你 通过 一 个 给 定 实例 构建 一 个 条 件 
查询 。 


Cat cat = new Cat(); 

cat .setSex('F'); 

cat.setColor(Color.BLACK); 

List results = session.createCriteria(Cat.class) 
.add( Example.create(cat) ) 
eal lisse la) 


版 本 属性 、 标 识 符 和 关联 被 忽略 。 默 认 情 况 下 值 为 null 的 属性 将 被 排除 。 
你 可 以 自行 调整 Example 使 之 更 实用 。 
Example example = Example.create(cat) 


.excludeZeroes() //exclude zero valued properties 
.excludeProperty("color") //exclude the property named "col 


or" 

. ignoreCase() //perform case insensitive string 
comparisons 

.enableLike(); //use like for string comparisons 
List results = session.createCriteria(Cat.class) 

. add (example) 

TESEO 


你 其 至 可 以 使 用 examples 在 关联 对 象 上 放置 条 件 。 


List results = session.createCriteria(Cat.class) 
.add( Example.create(cat) ) 
.createCriteria("mate") 

.add( Example.create( cat.getMate() ) ) 
ALLS EG ys 


15.7. 投影 (Projections)、 采 合 (aggregation) 和 
分 组 (grouping ) 


org.hibernate.criterion.Projections Æ Projection 的 实例 工厂 。 我 们 
通过 调用 setProjection() 应 用 投影 到 一 个 查询 。 


List results = session.createCriteria(Cat.class) 
.setProjection( Projections.rowCount() ) 
.add( Restrictions.eq("color", Color.BLACK) ) 
Sela sya Glee 


List results = session.createCriteria(Cat.class) 
.setProjection( Projections.projectionList() 
.add( Projections.rowCount() ) 
.add( Projections.avg("weight") ) 
.add( Projections.max("weight") ) 
.add( Projections.groupProperty("color") ) 


) 
.list(); 


在 一 个 条 件 查询 中 没有 必要 显 式 的 使 用 "group by" 。 某 些 投影 类 型 就 是 被 定义 为 
分 组 投影 ， 他 们 也 出 现在 SQL 的 group by FAF ° 


你 可 以 选择 把 一 个 别名 指派 给 一 个 投影 ， 这 样 可 以 使 投影 值 被 约束 或 排序 所 引用 。 
下 面 是 两 种 不 同 的 实现 方式 : 


List results = session.createCriteria(Cat.class) 

.setProjection( Projections.alias( Projections.groupProperty 
全 colon colr =). ) 

.addOrder( Order.asc("colr") ) 

ISEO: 


List results = session.createCriteria(Cat.class) 
.setProjection( Projections.groupProperty("color").as("colr" 


) ) 
.addOrder( Order.asc("colr") ) 


.list(); 


alias() 和 as() 方法 简便 的 将 一 个 投影 实例 包装 到 另外 一 个 别名 
的 Projection 实例 中 。 简 而 言 之 ， 当 你 添加 一 个 投影 到 一 个 投影 列表 中 时 你 可 
以 为 它 指定 一 个 别名 : 


List 


List 


results = session.createCriteria(Cat.class) 
.setProjection( Projections.projectionList() 
.add( Projections.rowCount(), "catCountByColor" ) 
.add( Projections.avg("weight"), "avgWeight" ) 
.add( Projections.max("weight"), "maxWeight" ) 
.add( Projections.groupProperty("color"), "color" ) 


) 


.addOrder( Order.desc("catCountByColor") ) 
.addOrder( Order.desc("avgWeight") ) 
SEO 


results = session.createCriteria(Domestic.class, "cat") 
.createAlias("kittens", "kit") 
.setProjection( Projections.projectionList() 
.add( Projections.property("cat.name"), "catName" ) 
.add( Projections.property("kit.name"), "kitName" ) 


.addOrder( Order.asc("catName") ) 
.addOrder( Order.asc("kitName") ) 
SEON 


你 也 可 以 使 用 Property. forNname() 来 表示 投影 : 


List 


List 


results = session.createCriteria(Cat.class) 
.setProjection( Property.forName("name") ) 

.add( Property.forName("color").eq(Color.BLACK) ) 
ellen Moye pal hea 


results = session.createCriteria(Cat.class) 

.setProjection( Projections.projectionList() 
.add( Projections.rowCount().as("catCountByColor") ) 
.add( Property.forName("weight").avg().as("avgWeight") ) 
.add( Property.forName("weight").max().as("maxWeight") ) 
.add( Property.forName("color").group().as("color" ) 

) 

.addOrder( Order.desc("catCountByColor") ) 

.addOrder( Order.desc("avgWeight") ) 

SES Ty 


15.8. 离线 (detached) 查 询 和 子 查 询 


DetachedCriteria 类 使 你 在 一 个 session 范 围 之 外 创建 一 个 查询 ， 并 且 可 以 使 用 
任意 的 Session 来 执行 它 。 


DetachedCriteria query = DetachedCriteria.forClass(Cat.class) 
.add( Property.forName("sex").eq('F') ); 


Session session = ....; 

Transaction txn = session.beginTransaction(); 

List results = query.getExecutableCriteria(session).setMaxResult 
s(100).list(); 

txn.commit(); 

session.close(); 


DetachedCriteria 也 可 以 用 以 表示 子 查询 。 条 件 实例 包含 子 查 询 可 以 通过 
Subqueries 或 者 Property 获得 。 


DetachedCriteria avgWeight = DetachedCriteria.forClass(Cat.class 
) 

.setProjection( Property. forName("weight").avg() ); 
session.createCriteria(Cat.class) 

.add( Property.forName("weight).gt(avgweight) ) 

ISEO) 


DetachedCriteria weights = DetachedCriteria.forClass(Cat.class) 
.setProjection( Property.forName("weight") ); 
session.createCriteria(Cat.class) 
.add( Subqueries.geAll("weight", weights) ) 
DES C0) 


甚至 相互 关联 的 子 查询 也 是 有 可 能 的 : 


DetachedCriteria avgWeightForSex = DetachedCriteria.forClass(Cat 
.Class, "cat2") 

.setProjection( Property.forName("weight").avg() ) 

.add( Property.forName("cat2.sex").eqProperty("cat.sex") ); 
session.createCriteria(Cat.class, "cat") 

.add( Property.forName("weight).gt(avgweightForSex) ) 

TESEO 
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15.9. 根据 目 多 查询 (Queries by natural 
identifier) 


对 大 多 数 查 询 ， 包 括 条 件 查询 而 言 nn 
繁 ， 查 询 缓存 不 是 非常 癌 效 。 然而， 有 一 种 特别 的 查询 ， 可 以 通过 不 变 的 自然 键 优 
化 缓存 的 失效 算法 。 在 某 些 应 用 中 ， 这 种 类 型 的 查询 比较 常见 。 条 件 查询 API 对 这 
种 用 例 提供 了 特别 规约 。 


你 应 该 对 你 的 entity 使 用 &lt;natural-id&gt; 来 映射 自然 键 ， 然 后 打开 第 
级 TES 


<class name="User"> 
<cache usage="read-write"/> 
<id name="id"> 
<generator class="increment"/> 
</id> 
<natural-id> 
<property name="name"/> 
<property name="org"/> 
</natural-id> 
<property name="password"/> 
</class> 


注意 ,此 功能 对 具有 mutable 自 然 键 的 entity 并 不 适用 
然后 ， 打 开 Hibernate 查询 缓存 。 
现在 ， 我 们 可 以 用 Restrictions.naturalId() 来 使 用 更 加 高 效 的 缓存 算法 。 


session.createCriteria(User.class) 
.add( Restrictions.naturallId() 
.set("name", "gavin") 
.set("org", "hb") 
).setCacheable(true) 
.uniqueResult(); 


第 16 = Native SQL 查询 


目录 


e 16.1. 使 用 SQLQuery 
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你 也 可 以 使 用 你 的 数据 库 的 Native SQL 语言 来 查询 数据 。 这 对 你 在 要 使 用 数据 库 的 
某 些 特性 的 时 候 ( 比 如 说 在 查询 提示 或 者 Oracle 中 的 CONNECT 关键 字 )， 这 是 非常 
有 用 的 。 这 就 能 够 扫 清 你 把 原来 直接 使 用 SQL/JDBC 的 程序 迁移 到 基于 Hibernate 
应 用 的 道路 上 的 障碍 。 


Hibernate3 允 许 你 使 用 手写 的 sq| 来 完成 所 有 的 create,update,delete, 和 |oad 操 作 
(包括 存储 过 程 ) 


O O O O O 0 0 


16.1. 使 用 SQLQuery 


对 原生 SQL 查询 执行 的 控制 是 通过 SQLQuery 接口 进行 的 ， 通 过 执 
行 Session.createSQLQuery() 获取 这 个 接口 。 下 面 来 描述 如 何 使 用 这 个 API 进 
行 查询 。 


16.1.1. 标量 查询 (Scalar queries ) 
最 基本 的 SQL 查询 就 是 获得 一 个 标量 (数值 ) 的 列表 。 


sess.createSQLQuery("SELECT * FROM CATS").1list(); 
sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE FROM CATS").list 


(); 


它们 都 将 返回 一 个 Object 数组 (Object[]) 组 成 的 List， 数 组 每 个 元 素 都 是 CATS 表 的 一 
个 字段 值 。Hibernate 会 使 用 ResultSetMetadata 来 判定 返回 的 标量 值 的 实际 顺序 和 
类 型 。 


如 果 要 避免 过 多 的 使 用 ResultSetMetadata ,或 者 只 是 为 了 更 加 明确 的 指名 返回 
值 ， 可 以 使 用 addScalar() ° 


sess.createSQLQuery("SELECT * FROM CATS") 
.addScalar("ID", Hibernate. LONG) 
.addScalar("NAME", Hibernate.STRING) 
.addScalar("BIRTHDATE", Hibernate.DATE) 


这 个 查询 指定 了 : 
e SQL 查询 字符 串 
e 要 返回 的 字段 和 类 型 


它 仍然 会 返回 Object 数组 ,但 是 此 时 不 再 使 用 ResultSetMetdata ,而 是 明确 的 将 
ID,NAME 和 BIRTHDATE 按 照 Long,String 和 Short 类 型 从 resultset 中 取出 。 同 时 ， 也 
指明 了 就 算 query 是 使 用 * 来 查询 的 ， 可 能 获得 超过 列 出 的 这 三 个 字段 ， 也 仅仅 会 
返回 这 三 个 字段 。 


对 全 部 或 者 部 分 的 标量 值 不 设置 类 型 信息 也 是 可 以 的 。 


sess.createSQLQuery("SELECT * FROM CATS") 
.addScalar("ID", Hibernate. LONG) 
.addScalar ("NAME") 
.addScalar ("BIRTHDATE") 


基本 上 这 和 前 面 一 个 查询 相同 ,只 是 此 时 使 用 ResultSetMetaData 来 决定 NAME 和 
BIRTHDATE 的 类 型 ， 而 ID 的 类 型 是 明确 指出 的 。 


关于 从 ResultSetMetaData 返 回 的 java.sql.Types 是 如 何 映射 到 Hibernate 类 型 ， 是 由 
方言 (Dialect) 控 制 的 。 假 若 某 个 指定 的 类 型 没有 被 映射 ， 或 者 不 是 你 所 预期 的 类 
型 ， 你 可 以 通过 Dialet 的 registerHibernateType 调用 自行 定义 。 
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16.1.2. 实体 查询 (Entity queries) 


7 ene > 也 就 是 从 resultset 中 返回 的 “ 裸 ? 数 据 。 下 面 展示 如 
何 通过 addEntity() 让 原生 查询 返回 实体 对 象 。 


sess.createSQLQuery("SELECT * FROM CATS").addEntity(Cat.class); 
sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE FROM CATS") .addE 
ntity(Cat.class); 


这 个 查询 指定 
e。 SQL 查询 字符 串 
o 要 返回 的 实体 


假设 Cat 被 映射 为 拥有 ID,NAME 和 BIRTHDATE 三 个 字段 的 类 ， 以 上 的 两 个 查询 都 返 
回 一 个 List， 每 个 元 素 都 是 一 个 Cat 实 体 。 


假若 实体 在 映射 时 有 一 个 many- to-one 的 关联 指向 另外 一 个 实体 ， 在 查询 时 必须 
也 返回 那个 实体 ， 否 则 会 a Sora no found" 的 数据 库 错 误 。 这 些 附加 
的 字段 可 以 使 用 * 标 注 来 自动 返回 ， 但 我 们 希望 还 是 明确 指明 ， 看 下 面 这 个 具有 指 
向 Dog 的 many-to-one 的 例子 


sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE, DOG_ID FROM CAT 
S").addEntity(Cat.class); 


这 样 cat.getDog() 就 能 正常 运作 。 


16.1.3. 处 理 关 联 和 集合 类 (Handling associations 
and collections) 


通过 提前 抓 取 将 Dog 连接 获得 ， 而 避免 初始 化 proxy 带 来 的 额外 开销 也 是 可 能 的 。 
这 是 通过 addJoin() 方法 进行 的 ， 这 个 方法 可 以 让 你 将 关联 或 全 合 连接 进来 。 


sess.createSQLQuery("SELECT c.ID, NAME, BIRTHDATE, DOG_ID, D_ID, 
D_NAME FROM CATS c, DOGS d WHERE c.DOG_ID = d.D_ID") 
.addEntity("cat", Cat.class) 

.addJoin("cat.dog"); 


上 面 这 个 例子 中 ， 返 回 的 cat 对 象 ， 其 dog 属性 被 完全 初始 化 了 ， 不 再 需要 数据 
库 的 额外 操作 。 注 意 ， 我 们 加 了 一 个 别名 ("cat")， 以 便 指 明 join 的 目标 属性 路 径 。 通 
过 同样 的 提前 连接 也 可 以 作用 于 集合 类 ， 例 如 ， 假 若 cat 有 一 个 指向 Dog 的 一 对 
多 关联 。 


sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE, D_ID, D_NAME, C 
AT_ID FROM CATS c, DOGS d WHERE c.ID = d.CAT_ID") 
.addEntity("cat", Cat.class) 
.addJoin("cat.dogs"); 


到 此 为 止 ， 我 们 碰 到 了 天 花 板 : 老 不 对 SQL 得 询 进 行 增强 ， 这 些 已 经 是 在 Hibernate 
中 使 用 原 生 SQL 查 询 所 有 EE 做 到 的 最 大 可 能 了 。 下 面 的 问题 即将 出 现 : 返回 多 个 同样 
类 型 的 实体 怎么 办 ?或 者 默认 的 别名 /字段 不 够 又 怎么 


16.1.4. 返回 多 个 实体 (Returning multiple 
entities) 


到 目前 为 止 ,结果 集 字段 名 被 假定 为 和 映射 文件 中 指定 的 的 字段 名 是 一 致 的 。 假 若 
SQL 查询 连接 了 多 个 表 ， 同 一 个 字段 名 可 能 在 多 个 表 中 出 现 多 次 ， 这 就 会 造成 问 
是 o 


下 面 的 查询 中 需要 使 用 字段 别名 注射 (这 个 例子 本 身 会 失败 ) 


sess.createSQLQuery("SELECT c.*, m.* FROM CATS c, CATS m WHERE 
c.MOTHER_ID = c.ID") 

.addEntity("cat", Cat.class) 

.addEntity("mother", Cat.class) 


这 个 查询 的 本 意 是 硕 望 每 行 返 回 两 个 Cat 实 例 ， 一 个 是 cat, 另 一 个 是 它 的 妈妈 。 但 是 
因为 它们 的 字段 名 被 映射 为 相同 的 ， 而 且 在 某 些 数据 库 中 ， 返 回 的 字段 别名 

是 “c.ID”,"c.NAME" 这 样 的 形式 ， 而 它们 和 在 映射 文件 中 的 名 字 〈"ID" 和 "NAME") 
不 匹配 ， 这 就 会 造成 失败 。 


下 面 的 形式 可 以 解决 字段 名 重复 : 


sess.createSQLQuery("SELECT {cat.*}, {mother.*} FROM CATS c, CA 
TS m WHERE c.MOTHER_ID = c.ID") 

.addEntity("cat", Cat.class) 

.addEntity("mother", Cat.class) 


这 个 查询 指明 : 

e。 SQL 查 询 语 名 ， 其 中 包含 占 位 附 来 让 Hibernate 注 射 字 段 别 名 

o 查询 返回 的 实体 
上 面 使 用 的 {cat.} 和 {mother} 标 记 是 作为 “所 有 属性 "的 简写 形式 出 现 的 。 当 然 你 也 可 
以 明确 地 罗列 出 字段 名 ， 但 在 这 个 例子 里 面 我 们 让 Hibernate 来 为 每 个 属性 注射 SQL 
字段 别名 。 字 段 别 名 的 占 位 符 是 属性 名 加 上 表 别 名 的 前 级 。 在 下 面 的 例子 中 ， 我 们 
从 另外 一 个 表 (cat_log) 中 通过 映射 元 数据 中 的 指定 获取 Cat 和 它 的 妈妈 。 注 意 ， 
要 是 我 们 愿意 ， 我 们 甚至 可 以 在 where 子 名 中 使 用 属性 别名 。 


String sql = "SELECT ID as {c.id}, NAME as {c.name}, " + 
"BIRTHDATE as {c.birthDate}, MOTHER_ID as {c.mother}, { 
mother.*} "+ 
"FROM CAT_LOG c, CAT_LOG m WHERE {c.mother} = c.ID"; 


List loggedCats = sess.createSQLQuery(sql) 
.addEntity("cat", Cat.class) 
.addEntity("mother", Cat.class).list() 


16.1.4.1. 别名 和 属性 引用 (Alias and property 
references) 

大 多 数 情 况 下 ， 都 需要 上 面 的 属性 注射 ， 但 在 使 用 更 加 复杂 的 映射 ， 比 如 复合 属 
性 、 通 过 标识 符 构造 继承 树 ， 以 及 集合 类 等 等 情况 下 ， 也 有 一 些 特别 的 别名 ， 来 多 
许 Hibernate 注 射 合适 的 别名 。 


下 表 列 出 了 使 用 别名 注射 参数 的 不 同 可 能 性 。 注 意 : 
实用 时 每 个 别名 需要 唯一 并 且 不 同 的 名 字 。 


表 16.1. 别名 注射 (alias injection names) 


下 面 结果 中 的 别名 只 是 示例 ， 


描述 语法 
简单 属性 {[aliasname].[propertyname] AN 
复合 属性 {[aliasname] .[componentname].[propertyname ] } CUF 
实体 辨别 器 
(Discriminator {[aliasname].class} DIS 
of an entity) 
as {[aliasname].*} fal 
集合 键 
(collection {[aliasname] . key} ORC 
key) 
集合 id {[aliasname] .id} EMF 
集合 元 素 {[aliasname].element} XIL 
a se {[aliasname].element.[propertyname ] } NAN 
n {[aliasname].element.*} {cc 
a {[aliasname].*} {cc 


O 


16.1.5. 返回 非 受 管 实体 (Returning non-managed 
entities) 


可 以 对 原生 sq| 查询 使 用 ResultTransformer。 这 会 返回 不 受 Hibernate 管 理 的 实体 。 


sess.createSQLQuery("SELECT NAME, BIRTHDATE FROM CATS") 
.setResultTransformer(Transformers.aliasToBean(CatDTO.cl 
ass)) 


这 个 查询 指定 : 
e SQL 查询 字符 串 
o 结果 转换 器 (result transformer) 


上 面 的 查询 将 会 返回 CatDT0 的 列表 , 它 将 被 实例 化 并 且 将 NAME 和 BIRTHDAY 的 值 
注射 入 对 应 的 属性 或 者 字段 。 


16.1.6. 处 理 继承 (Handling inheritance ) 


原生 SQL 查询 假若 其 查询 结果 实体 是 继承 树 中 的 一 部 分 ， 它 必须 包含 基 类 和 所 有 子 
类 的 所 有 属性 。 


16.1.7. 参数 (Parameters ) 
原生 查询 支持 位 置 参 数 和 命名 参数 : 


Query query = sess.createSQLQuery("SELECT * FROM CATS WHERE NAME 
like ?").addEntity(Cat.class); 


List pusList = query.setString(0, "Pus%").list(); 


query = sess.createSQLQuery("SELECT * FROM CATS WHERE NAME like 
:name").addEntity(Cat.class); 


List pusList = query.setString("name", "Pus%").list(); 


16.2. 命名 SQL 查询 


可 以 在 映射 文档 中 定义 查询 的 名 字 , 然后 就 可 以 象 调用 一 个 命名 的 HQL 查 询 一 样 直接 
调用 命名 SQL 查询 .在 这 种 情况 下 ,我 们 不 需要 调用 addEntity() 方法 . 


<sql-query name="persons"> 
<return alias="person" class="eg.Person"/> 
SELECT person.NAME AS {person.name}, 
person.AGE AS {person.age}, 
person.SEX AS {person.sex} 
FROM PERSON person 
WHERE person.NAME LIKE :namePattern 
</sql-query> 


List people = sess.getNamedQuery("persons" ) 
.setString("namePattern", namePattern) 
.setMaxResults(50) 

.list(); 


&lt;return-join&gt; 和 &lt;load-collection&gt; 元 素 是 用 来 连接 关联 以 
及 将 查 询 定义 为 预先 初始 化 各 个 集合 的 。 


<sql-query name="personsWith"> 
<return alias="person" class="eg.Person"/> 
<return-join alias="address" property="person.mailingAddress 
u 
SELECT person.NAME AS {person.name}, 
person. AGE AS {person.age}, 
person.SEX AS {person.sex}, 
adddress.STREET AS {address.street}, 
adddress.CITY AS {address.city}, 
adddress.STATE AS {address.state}, 
adddress.ZIP AS {address.zip} 
FROM PERSON person 
JOIN ADDRESS adddress 
ON person.ID = address.PERSON_ID AND address. TYPE='MAILI 
NG' 
WHERE person.NAME LIKE :namePattern 
</sql-query> 


一 个 命名 查询 可 能 会 返回 一 个 标量 值 .你 必须 使 用 @lt;return-scalar&égt; 元 素 
来 指定 字段 的 别名 和 Hibernate 类 型 


<sql-query name="mySqlQuery"> 
<return-scalar column="name" type="string"/> 
<return-scalar column="age" type="long"/> 
SELECT p.NAME AS name, 
p.AGE AS age, 
FROM PERSON p WHERE p.NAME LIKE 'Hiber%' 
</sql-query> 


你 可 以 把 结果 集 映 射 的 信息 放 在 外 部 的 Blt; resultseta&gt; 元 素 中 ， 这 样 就 可 以 
在 多 个 命名 查询 间 ， 或 者 通过 setResultSetMapping() APl 来 访问 。( 此 处 原文 即 
存疑 。 原 文 为 : You can externalize the resultset mapping informations in a 

&lt;resultset&gt; element to either reuse them accross several named 
queries or through the setResultSetMapping() API.) 


<resultset name="personAddress"> 

<return alias="person" class="eg.Person"/> 

<return-join alias="address" property="person.mailingAddress 
WS 
</resultset> 


<sql-query name="personsWith" resultset-ref="personAddress"> 
SELECT person.NAME AS {person.name}, 
person.AGE AS {person.age}, 
person.SEX AS {person.sex}, 
adddress.STREET AS {address.street}, 
adddress.CITY AS {address.city}, 
adddress.STATE AS {address.state}, 
adddress.ZIP AS {address.zip} 
FROM PERSON person 
JOIN ADDRESS adddress 
ON person.ID = address.PERSON_ID AND address. TYPE='MAILI 
NG' 
WHERE person.NAME LIKE :namePattern 
</sql-query> 


另外 ,你 可 以 在 java 代 码 中 直接 使 用 hbm 文 件 中 的 结果 集 定义 信息 。 


List cats = sess.createSQLQuery( 
"select {cat.*}, {kitten.*} from cats cat, cats kitten w 
here kitten.mother = cat.id" 
) 
.setResultSetMapping("catAndKitten") 
TESEO 
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16.2.1. 使 用 return-property 来 明确 地 指定 字段 / 别 
加 


使 用 &lt;return-propertyagt; 你 可 以 明确 的 告诉 Hibernate 使 用 哪些 字段 别名 ， 
这 取代 了 使 用 {} -语法 来 让 Hibernate 注 入 它 自己 的 别名 


<sql-query name="mySqlQuery"> 
<return alias="person" class="eg.Person"> 
<return-property name="name" column="myName"/> 
<return-property name="age" column="myAge"/> 
<return-property name="sex" column="mySex"/> 
</return> 
SELECT person.NAME AS myName, 
person.AGE AS myAge, 
person.SEX AS mySex, 
FROM PERSON person WHERE person.NAME LIKE :name 
</sql-query> 


<return-property> 也 可 用 于 多 个 字段 , 它 解 决 了 使 用 {} -语法 不 能 细 粒 度 控制 
多 个 字段 的 限制 


<sql-query name="organizationCurrentEmployments"> 
<return alias="emp" class="Employment"> 
<return-property name="salary"> 
<return-column name="VALUE"/> 
<return-column name="CURRENCY"/> 
</return-property> 
<return-property name="endDate" column="myEndDate"/ 


= 

</return> 

SELECT EMPLOYEE AS {emp.employee}, EMPLOYER AS {emp. 
employer}, 

STARTDATE AS {emp.startDate}, ENDDATE AS {emp.endDat 
e}, 


REGIONCODE as {emp.regionCode}, EID AS {emp.id}, VAL 
UE, CURRENCY 

FROM EMPLOYMENT 

WHERE EMPLOYER = :id AND ENDDATE IS NULL 

ORDER BY STARTDATE ASC 
</sql-query> 


注意 在 这 个 例 be &lt;return-property&gt; 结合 {} 的 注入 语 ; 
允许 用 户 来 选 择 如 何 引用 字段 以 及 属 ， 性 . 


如 果 你 映射 一 个 识别 器 (discriminator), 你 必须 使 
用 E E 来 指定 识别 器 字段 


16.2.2. 使 用 存储 过 程 来 查询 


Hibernate 3 引入 了 对 存储 过 程 查 询 (stored procedure) 和 函数 (function) 的 支持 .以 下 
的 说 明 中 ， 这 二 者 一 般 都 适用 。 存储 过 程 /函数 必须 返回 一 个 结果 集 , 作 为 Hibernate 
能 够 使 用 的 第 一 个 外 部 参数 . 下 面 是 一 个 Oracle9 和 更 高 版 本 的 存储 过 程 例子 . 


CREATE OR REPLACE FUNCTION selectAllEmployments 
RETURN SYS_REFCURSOR 
AS 
st_cursor SYS _REFCURSOR; 
BEGIN 
OPEN st_cursor FOR 
SELECT EMPLOYEE, EMPLOYER, 
STARTDATE, ENDDATE, 
REGIONCODE, EID, VALUE, CURRENCY 
FROM EMPLOYMENT; 
RETURN st_cursor; 
END; 


在 Hibernate 里 要 要 使 用 这 个 查询 ,你 需要 通过 命名 查询 来 映射 它 . 


<sql-query name="selectAllEmployees_SP" callable="true"> 
<return alias="emp" class="Employment"> 
<return-property name="employee" column="EMPLOYEE"/> 
<return-property name="employer" column="EMPLOYER"/> 


<return-property name="startDate" column="STARTDATE"/> 
<return-property name="endDate" column="ENDDATE"/> 


<return-property name="regionCode" column="REGIONCODE"/> 
<return-property name="id" column="EID"/> 


<return-property name="Salary"> 
<return-column name="VALUE"/> 
<return-column name="CURRENCY"/> 
</return-property> 
</return> 
{ ? = call selectAllEmployments() } 
</sql-query> 


注意 存储 过 程 当前 仅仅 返回 标量 和 实体 .现在 不 支 
持 &lt;return-join&gt; 和 &lt;load-collectionggt; 
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16.2.2.1. 使 用 存储 过 程 的 规则 和 限制 


为 了 在 Hibernate 中 使 用 存储 过 程 ,你 必须 遵循 一 些 规则 .不 遵循 这 些 规 则 的 存储 过 程 
将 不 可 用 .如 果 你 仍然 想 要 使 用 他 们 , 你 必须 通过 session.connection() 来 执行 
他 们 .这 些 规则 针对 于 不 同 的 数据 库 .因为 数据 库 提供 商 有 各 种 不 同 的 存储 过 程 语法 
和 语义 . 


对 存储 过 程 进 行 的 查询 无 法 使 用 setFirstResult()/setMaxResults() 进行 分 
页 。 


建议 采用 的 调用 方式 是 标准 SQL92: 


{ ? = call functionName(&lt;parameters&gt;) } 或 者 
{ ? = call procedureName(&lt;parameters&gt;} .原生 调用 语法 不 被 支持 。 
对 于 Oracle 有 如 下 规则 : 


© 函数 必须 返回 一 个 结果 集 。 存 储 过 程 的 第 一 个 参数 必须 是 OUT ， 它 返回 一 个 
结果 集 。 这 是 通过 Oracle 9 或 10 的 SYS_REFCURSOR 类 型 来 完成 的 。 在 Oracle 
中 你 需要 定义 一 个 REF CURSOR 类型， 参见 Oracle 的 手册 。 
对 于 Sybase 或 者 MS SQL server 有 如 下 规则 : 


o 存储 过 程 必须 返回 一 个 结果 集 。. 注 意 这 些 Servers 可 能 返回 多 个 结果 集 以 及 更 
新 的 数目 .Hibernate 将 取出 第 一 条 结果 集 作为 它 的 返回 值 ， 其 他 将 被 丢弃 。 


o 如 果 你 能 够 在 存储 过 程 里 设 定 SET NOCOUNT ON ， 这 可 能 会 效率 更 高 ， 但 这 
不 是 必需 的 。 


16.3. 定制 SQL 用 来 create，update 和 delete 


Hibernate3 能 够 使 用 定制 的 SQL 语 句 来 执行 create,update 和 delete 操 作 。 在 

Hibernate 中 ， 持 久 化 的 类 和 集合 已 经 包含 了 一 套 配 置 期 产生 的 语句 (insertsql, 

deletesql, updatesql 等 等 )， 这 些 映射 标记 &lt;sql-insert&gt; , 
&lt;sql-deleteagt; ,and &lt;sql-updateagt; BAT AEH eo 


<class name="Person"> 
<id name="id"> 
<generator class="increment"/> 
</id> 
<property name="name" not-null="true"/> 
<sql-insert>INSERT INTO PERSON (NAME, ID) VALUES ( UPPER(?), 
? )</sql-insert> 
<sql-update>UPDATE PERSON SET NAME=UPPER(?) WHERE ID=?</sql- 


update> 
<sql-delete>DELETE FROM PERSON WHERE ID=?</sql-delete> 


</class> 


这 些 SQL 直 接 在 你 的 数据 库 里 执行 ， 所 以 你 可 以 自由 的 使 用 你 喜欢 的 任意 语法 。 但 
如 果 你 使 用 数据 库 特 定 的 语法 ， 这 当然 会 降低 你 映射 的 可 移植 性 。 


如 果 设 定 callable ， 则 能 够 支持 存储 过 程 了 。 


<class name="Person"> 
<id name="id"> 
<generator class="increment"/> 
</id> 
<property name="name" not-null="true"/> 
<sql-insert callable="true">{call createPerson (?, ?)}</sql- 


insert> 
<sql-delete callable="true">{? = call deletePerson (?)}</sql 


-delete> 
<sql-update callable="true">{? 


sql-update> 
</class> 


= call updatePerson (?, ?)}</ 


参数 的 位 置 顺序 是 非常 重要 的 ， 他 们 必须 和 Hibernate 所 期 待 的 顺序 相同 。 


尔 能 够 通过 设 定 日 志 调 试 级 别 为 org.hiberante.persister.entity ,来 查看 
Hibernate 所 期 待 的 顺序 。 在 这 个 级 别 下 ，Hibernate 将 会 打印 出 create,update 和 
delete 实 体 的 静态 SQL。( 如 果 想 看 到 预计 的 顺序 。 记 得 不 要 将 定制 SQL 包 含 在 映射 
文件 里 ， 因 为 他 们 会 重 载 Hibernate 生 成 的 静态 SQL。) 


在 大 多 数 情 况 下 (最 好 这 么 做 )， 存 储 过 程 需要 返回 插入 /更 新 /删除 的 行 数 ， 因 为 
Hibernate 对 语句 的 成 功 执 行 有 些 运 行 时 的 检查 。 Hibernate 常 会 把 进行 CUD 操 作 的 
语句 的 第 一 个 参数 注册 为 一 个 数值 型 输出 参数 。 


CREATE OR REPLACE FUNCTION updatePerson (uid IN NUMBER, uname IN 
VARCHAR2 ) 

RETURN NUMBER IS 
BEGIN 


update PERSON 
set 

NAME = uname, 
where 

ID = uid; 


return SQL%ROWCOUNT ; 


END updatePerson; 


x 


16.4. 定制 装载 SQL 
你 可 能 需要 声明 你 自己 的 SQL( 或 HQL) 来 装载 实体 


<sql-query name="person"> 


<return alias="pers" class="Person" lock-mode="upgrade"/> 


SELECT NAME AS {pers.name}, ID AS {pers.id} 
FROM PERSON 
WHERE ID=? 
FOR UPDATE 
</sql-query> 


这 只 是 一 个 前 面 讨论 过 的 命名 查询 声明 ， 你 可 以 在 类 映射 里 引用 这 个 


<class name="Person"> 
<id name="id"> 
<generator class="increment"/> 
</id> 
<property name="name" not-null="true"/> 
<loader query-ref="person"/> 
</class> 


这 也 可 以 用 于 存储 过 程 
你 甚至 可 以 定 一 个 用 于 集合 装载 的 查询 ; 


<set name="employments" inverse="true"> 
<key/> 
<one-to-many class="Employment"/> 
<loader query-ref="employments"/> 
</set> 


<sql-query name="employments"> 


<load-collection alias="emp" role="Person.employments"/> 


SELECT {emp.*} 

FROM EMPLOYMENT emp 

WHERE EMPLOYER = :id 

ORDER BY STARTDATE ASC, EMPLOYEE ASC 
</sql-query> 


你 甚至 还 可 以 定义 一 个 实体 装载 器 ， 它 通过 连接 抓 取 装 载 一 个 集合 : 


命 


名 


询 。 


<sql-query name="person"> 
<return alias="pers" class="Person"/> 
<return-join alias="emp" property="pers.employments"/> 
SELECT NAME AS {pers.*}, {emp.*} 
FROM PERSON pers 
LEFT OUTER JOIN EMPLOYMENT emp 
ON pers.ID = emp.PERSON_ID 
WHERE ID=? 
</sql-query> 
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17.1. Hibernate 33 4 (filters) 


Hibernate3 新 增 了 对 某 个 类 或 者 集合 使 用 预先 定义 的 过 滤器 条 件 (filter criteria) 的 功 
能 。 过 滤器 条 件 相当 于 定义 一 个 非常 类 似 于 类 和 各 种 集合 上 的 “where” 属 性 的 约束 
子 句 ， 但 是 过 滤器 条 件 可 以 带 参 数 。 应 用 程序 可 以 在 运行 时 决定 是 否 启 用 给 定 的 过 
滤器 ， 以 及 使 用 什么 样 的 参数 值 。 过 滤器 的 用 法 很 像 数 据 库 视图 ， 只 不 过 是 在 应 用 
程序 中 确定 使 用 什么 样 的 参数 的 。 


要 使 用 过 滤器 ， 必 须 首 先 在 相应 的 映射 节点 中 定义 。 而 定义 一 个 过 滤器 ， 要 用 到 位 
于 &lt;hibernate-mapping/&gt; 节点 之 内 的 &lt;filter-def/agt; 节点 : 


<filter-def name="myFilter"> 
<filter-param name="myFilterParam" type="string"/> 
</filter-def> 


定义 好 之 后 ， 就 可 以 在 茶 个 类 中 使 用 这 个 过 滤器 : 


<class name="myClass" ...> 


<filter name="myFilter" condition=":myFilterParam = MY_FILTE 
RED_COLUMN"/> 
</class> 


也 可 以 在 茶 个 集合 使 用 它 : 


<set ...> 

<filter name="myFilter" condition=":myFilterParam = MY_FILTE 
RED_COLUMN"/> 
</set> 


以 在 多 个 类 或 集合 中 使 用 某 个 过 滤器 ; 某 个 类 或 者 集合 中 也 可 以 使 用 多 个 过 滤 


o 


| 


2, 


me 
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Session 对 象 中 会 用 到 的 方法 有 : enableFilter(String filterName) , 
getEnabledFilter(String filterName) ,和 

disableFilter(String filterName) .Session 中 默认 是 不 局 用 过 滤器 的 ， 必 须 
通过 Session.enabledFilter() 方法 显 式 的 启用 。 该 方法 返回 被 启用 

的 Filter 的 实例 。 以 上 文 定义 的 过 滤器 为 例 : 


session.enableFilter("myFilter").setParameter("myFilterParam", " 
some-value"); 


(类 似 上 面 例子 中 启用 Filter 
之 后 设 定 Filter 参 数 这 个 “方法 链 ”") Hibernate 的 其 他 部 分 也 大 多 有 这 个 特性 。 


下 面 是 一 个 比较 完整 的 例子 ， 使 用 了 记录 生效 日 期 模式 过 滤 有 时 效 的 数据 : 


<filter-def name="effectiveDate"> 
<filter-param name="asOfDate" type="date"/> 
</filter-def> 


<class name="Employee" ...> 


<many-to-one name="department" column="dept_id" class="Depar 
tment"/> 

<property name="effectiveStartDate" type="date" column="eff_ 
start_dt"/> 

<property name="effectiveEndDate" type="date" column="eff_en 
d_dt"/> 


gis 
Note that this assumes non-terminal records have an eff_ 
end_dt set to 
a max db date for simplicity-sake 


注意 ， 为 了 简单 起 见 ， 此 处 假设 雇用 关系 生效 期 尚未 结束 的 记录 的 eff_end 
dt 字段 的 值 等 于 数据 库 最 大 的 日 期 
Ss 
<filter name="effectiveDate" 
condition=":asOfDate BETWEEN eff_start_dt and eff_en 
d_dt"/> 
</class> 


<class name="Department" ...> 


<set name="employees" lazy="true"> 
<key column="dept_id"/> 
<one-to-many class="Employee"/> 
<filter name="effectiveDate" 
condition=":asOfDate BETWEEN eff_start_dt and ef 
f_end_dt"/> 
</set> 
</class> 


定义 好 后 ， 如 果 想 要 保证 取 回 的 都 是 目前 处 于 生效 期 的 记录 ， 只 需 在 获取 雇员 数据 
的 操作 之 前 先 开启 过 滤器 即 可 : 


Session session = ...; 
session.enabledFilter("effectiveDate").setParameter("asOfDate", 
new Date()); 
List results = session.createQuery("from Employee as e where e.s 
alary > :targetSalary") 

.setLong("targetSalary", new Long(1000000) ) 

SEO 


在 上 面 的 HQL 中 ， 虽 然 我 们 仅仅 显 式 的 使 用 了 一 个 薪水 条 件 ， 但 因为 启用 了 过 滤 
器 ， 查 询 将 仅 返 回 那 些 目 前 雇用 关系 处 于 生效 期 的 ， 并 且 薪 水 高 于 一 百 万 美 刀 的 雇 
员 的 数据 。 


注意 : 如 果 你 打算 在 使 用 外 连接 (或 者 通过 HQL 或 load fetching) 的 同时 使 用 过 滤 
器 ， 要 注意 条 件 表 达 式 的 方向 ( 左 还 是 右 ) 。 最 安全 的 方式 是 使 用 左 外 连接 (left 
outer joining) 。 并 且 通 常 来 说 ， 先 写 参 数 ， 然 后 是 操作 符 ， 最 后 写 数 据 库 字段 

2 O 


在 Filter 定 义 之 后 , 它 可 能 被 附加 到 多 个 实体 和 /或 集合 类 ,每 个 都 有 自己 的 条 件 。 假 若 
这 些 条 件 都 是 一 样 的 ， 每 次 都 要 定义 就 显得 很 繁 开 。 因 

此 ，&lt;filter-def/&gt， 被 用 来 定义 一 个 默认 条 件 ， 它 可 能 作为 属性 或 者 
CDATA 出 现 : 


<filter-def name="myFilter" condition="abc > xyz">...</filter-de 
f> 
<filter-def name="myOtherFilter">abc=xyz</filter-def> 


当 这 个 filter 被 附加 到 任何 目的 地 ， 而 又 没有 指明 条 件 时 ， 这 个 条 件 就 会 被 使 用 。 注 
意 ， 换 名 话说 ， 你 可 以 通过 给 filter 附 加 特别 的 条 件 来 重 载 默认 条 件 。 
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注意 这 是 Hiberate 3.0 的 一 个 实验 性 的 特性 。 这 一 特性 仍 在 积极 开发 中 。 


18.1. 用 XML 数据 进行 工作 


Hibernate 使 得 你 可 以 用 XML 数据 来 进行 工作 ， 恰 如 你 用 持久 化 的 POJO 进 行 工 作 那 
样 。 解 析 过 的 XML 树 可 以 被 认为 是 代替 POJO 的 另外 一 种 在 对 象 层 面 上 表示 关系 型 
数据 的 途径 . 
Hibernate 支 持 采 用 dom4j 作 为 操作 XML 树 的 APl。 你 可 以 写 一 些 查 询 从 数据 库 中 检 
索 出 dom4j 树 ， 随 后 你 对 这 颗 树 做 的 任何 修改 都 将 自动 同步 回 数 据 库 。 你 甚至 可 以 
用 dom4j 解 析 一 篇 XML 文 档 ， 然 后 使 用 Hibernate 的 任 一 基本 操作 将 它 写 入 数据 库 : 
persist(), saveOrUpdate(), merge(), delete(), replicate() (合并 操作 
merge() 目 前 还 不 支持 ) 。 


这 一 特性 可 以 应 用 在 很 多 场合 ， 包 括 数 据 导 入 导出 ， 通 过 JMS 或 SOAP 具 体 化 实体 
数据 以 及 基于 XSLT 的 报表 。 

一 个 单一 的 映射 就 可 以 将 类 的 属性 和 XML 文档 的 节点 同时 映射 到 数据 库 。 如 果 不 需 
要 映射 类 ， 它 也 可 以 用 来 只 映射 XML 文档 。 


18.1.1. 指定 同时 映射 XML 和 类 
这 是 一 个 同时 映射 POJO 和 XML 的 例子 : 


<class name="Account" 
table="ACCOUNTS" 
node="account"> 


<id name="accountId" 
column="ACCOUNT_ID" 
node="@id"/> 


<many-to-one name="Customer" 
column="CUSTOMER_ID" 
node="customer/@id" 
embed -xml="false"/> 


<property name="balance" 
column="BALANCE" 
node="balance"/> 


</class> 


18.1.2. 只 定义 XML 映射 
这 是 一 个 不 映射 POJO 的 例子 : 


<class entity-name="Account" 
table="ACCOUNTS" 
node="account"> 


<id name="id" 
column="ACCOUNT_ID" 
node="@id" 
type="string"/> 


<many-to-one name="CustomerId" 
column="CUSTOMER_ID" 
node="customer/@id" 
embed-xml="false" 
entity-name="Customer"/> 


<property name="balance" 
column="BALANCE" 
node="balance" 
type="big_ decimal"/> 


</class> 


这 个 映射 使 得 你 既 可 以 把 数据 作为 一 棵 dom4j 树 那样 访问 ， 又 可 以 作为 由 属性 键 值 
对 (java Map s) 组 成 的 图 那样 访问 。 属 性 名 字 纯 粹 是 逻辑 上 的 结构 ， 你 可 以 在 HQL 
查询 中 引用 它 。 


18.2. XML 了 映射 元 数据 
许多 Hibernate 映 射 元 素 具 有 node 属性 。 这 使 你 可 以 指定 用 来 保存 属性 或 实体 数 
据 的 XML 属性 或 元 素 。 node 属性 必须 是 下 列 格式 之 一 : 
e "element-name" - 映射 为 指定 的 XML 元 素 
e "@attribute-name" - 映射 为 指定 的 XML 属性 
"." -映射 为 父 元 素 


e "element-name/@attribute-name" - 映射 为 指定 元 素 的 指定 属性 


对 于 集合 和 单 值 的 关联 ， 有 一 个 额外 的 embed-xml 属性 可 用 。 这 个 属性 的 缺 省 值 
71.( embed-xml="true" )。 如 果 embed-xml="true" ， 则 对 应 于 被 关联 实体 或 
值 类 型 的 集合 的 XML 树 将 直接 谋 入 拥有 这 些 关 联 的 实体 的 XML 树 中 。 和 否则， 如 

果 embed-xml="false" ， 那 么 对 于 单 值 的 关联 ， 仅 被 引用 的 实体 的 标识 符 出 现在 
XML 树 中 (被 引用 实体 本 身 不 出 现 )， 而 集合 则 根本 不 出 现 。 


你 应 该 小 心 ， 不 要 让 太 多 关联 的 embed-xml 属 性 为 盖 ( embed-xml="true" )， 因 为 
XML 不 能 很 好 地 处 理 循环 引用 | 


<class name="Customer" 
table="CUSTOMER" 
node="customer"> 


<id name="id" 
column="CUST_ID" 
node="@id"/> 


<map name="accounts" 
node=" : " 
embed-xml="true"> 
<key column="CUSTOMER_ID" 
not-null="true"/> 
<map-key column="SHORT_DESC" 
node="@short-desc" 
type="string"/> 
<one-to-many entity-name="Account" 
embed-xml="false" 
node="account"/> 
</map> 


<component name="name" 
node="name"> 
<property name="firstName" 
node="first-name"/> 
<property name="initial" 
node="initial"/> 
<property name="lastName" 
node="last-name"/> 
</component> 


</class> 


TERMI P > BATRA AK HE 5 (account id) 的 集合 ， 但 不 能 入 实际 的 帐 目 数 
据 。 下 面 的 HQL 查 询 : 


from Customer c left join fetch c.accounts where c.lastName like 
: LastName 


返回 的 数据 集 将 是 这 样 : 


<customer id="123456789"> 
<account id="987632567" short-desc="Savings"/> 
<account id="985612323" short-desc="Credit Card"/> 
<name> 
<first-name>Gavin</first-name> 
<initial>A</initial> 
<last -name>King</last -name> 
</name> 


</customer> 


如 果 你 把 一 对 多 映射 &lt;one-to-many&gt; 的 embed-xml 属 性 置 为 站 
( embed-xml="true" )， 则 数据 看 上 去 就 像 这样 : 


<customer id="123456789"> 

<account id="987632567" short-desc="Savings"> 
<customer id="123456789"/> 
<balance>100.29</balance> 

</account> 

<account id="985612323" short-desc="Credit Card"> 
<customer id="123456789"/> 
<balance>-2370.34</balance> 

</account> 

<name> 
<first-name>Gavin</first-name> 
<initial>A</initial> 
<last -name>King</last -name> 

</name> 


</customer> 


18.3. 操作 XML 数 据 


让 我 们 来 读 入 和 更 新 应 用 程序 中 的 XML 文 档 。 通 过 获取 一 个 dom4j 会 话 可 以 做 到 这 
一 点 : 


Document doc = ....; 


Session session = factory.openSession(); 
Session dom4jSession = session.getSession(EntityMode.DOM4J); 
Transaction tx = session.beginTransaction(); 


List results = dom4jSession 
.createQuery("from Customer c left join fetch c.accounts whe 
re c.lastName like :lastName") 
SES Tah, 
for ( int 1=0; i<results.size(); i++ ) { 
//add the customer data to the XML document 
Element customer = (Element) results.get(i); 
doc.add(customer); 


} 


tx.commit(); 
session.close(); 


Session session = factory.openSession(); 
Session dom4jSession = session.getSession(EntityMode.DOM4J); 
Transaction tx = session. beginTransaction(); 


Element cust = (Element) dom4jSession.get("Customer", customeriId 
); 
for ( int i=0; i<results.size(); i++ ) { 
Element customer = (Element) results.get(i); 
//change the customer name in the XML and database 
Element name = customer.element("name"); 
name.element("first-name").setText(firstName) ; 
name.element("initial").setText(initial); 
name.element("last-name").setText(lastName) ; 


} 


tx.commit(); 
session.close(); 


将 这 一 特色 与 Hibernate 的 replicate() 操作 结合 起 来 对 于 实现 的 基于 XML 的 数据 
导入 /导出 将 非常 有 用 . 


18.3. 操作 XML 数据 
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19.1. 抓 取 策略 (Fetching strategies) 


抓 取 策 略 (fetching strategy) 是 指 : 当 应 用 程序 需要 在 (Hibernate 实体 对 象 图 
的 ) 关联 关系 间 进 行 导 航 的 时 候 ，Hibernate 如 何 获取 关联 对 象 的 策略 。 抓 取 策 略 
可 以 在 O/R 映 射 的 元 数据 中 声明 ， 也 可 以 在 特定 的 HQL 

或 条 件 查 询 (Criteria Query) FERF H ° 


Hibernate3 定义 了 如 下 几 种 抓 取 策略 : 
e 连接 抓 取 (Join fetching) - Hibernate 通 过 在 SELECT 78 471% 


用 OUTER JOIN (外 连接 ) 来 获得 对 象 的 关联 实例 或 者 关联 集合 。 


e 查询 抓 取 (Select fetching) - 另外 发 送 一 条 SELECT 语句 抓 取 当 前 对 和 象 的 关 


联 实 体 或 集合 。 除 非 你 显 式 的 指定 lazy="false" 禁止 延迟 抓 取 (lazy 
fetching) ， 否 则 只 有 当 你 申 正 访问 关联 关系 的 时 候 ， 才 会 执行 第 二 条 select 语 


es 


子 查询 抓 取 (Subselect fetching) - 另外 发 送 一 条 SELECT 语句 抓 取 在 前 面 
查询 到 (或 者 抓 取 到 ) 的 所 有 实体 对 象 的 关联 集合 。 除 非 你 显 式 的 指 

定 lazy="false" 禁止 延迟 抓 取 (lazy fetching) > GM RA SHALL 
联 关系 的 时 候 ， 才 会 执行 第 二 条 Select 语句 。 


批量 抓 取 (Batch fetching) - 对 查询 抓 取 的 优化 方案 ， 通 过 指定 一 个 主键 或 
外 键 列 表 ，Hibernate 使 用 单条 SELECT 语句 获取 一 批 对 象 实例 或 集合 。 


Hibernate 会 区 分 下 列 各 种 情况 : 


Immediate fetching， 立 即 抓 取 - 当 宿 主 被 加 载 时 ， 关 联 、 集 合 或 属性 被 立即 抓 
取 。 


Lazy collection fetching > 1&8 RAI- 直到 应 用 程序 对 集合 进行 了 一 次 操作 
时 ， 集 合 才 被 抓 取 。 (对 集合 而 言 这 是 默认 行为 。) 


"Extra-lazy" collection fetching,"Extra-lazy" 集 合 抓 取 -对 集合 类 中 的 每 个 元 素 
而 言 ， 都 是 直到 需要 时 才 去 访问 数据 库 。 除 非 绝 对 必要 ，Hibernate 不 会 试图 去 
把 整个 集合 都 抓 取 到 内 存 里 来 《适用 于 非常 大 的 集合 ) © 


Proxy fetching > REIR - 对 返回 单 值 的 关联 而 言 ， 当 其 某 个 方法 被 调用 ， 而 
非 对 其 关键 字 进行 get 操 作 时 才 抓 取 。 


"No-proxy" fetching, 非 代理 抓 取 - 对 返回 单 值 的 关联 而 言 ， 当 实例 变量 被 访问 
的 时 候 进行 抓 取 。 与 上 面 的 代理 抓 取 相 比 ， 这 种 方法 没有 那么 “延迟 "得 厉害 (就 
算 只 访问 标识 符 ， 也 会 导致 关联 抓 取 ) 但 是 更 加 透明 ， 因 为 对 应 用 程序 来 说 ， 不 
再 看 到 proxy。 这 种 方法 需要 在 编译 期 间 进 行 字 节 码 增 强 操 作 ， 因 此 很 少 需 

用 到 。 


Lazy attribute jetching， 属 性 延迟 加 载 - 对 属性 或 返回 单 值 的 关联 而 言 ， 当 其 
实例 变量 被 访问 的 时 候 进 行 抓 取 。 需 要 编译 期 字 节 码 强 化 ， 因 此 这 一 方法 很 少 
是 必要 的 。 


这 里 有 两 个 正 交 的 概念 : 关联 何 时 被 抓 取 ， 以 及 被 如 何 抓 取 (会 采用 什么 样 的 SQL 
语句 ) 。 不 要 混淆 它们 ! 我 们 使 用 抓 取 来 改善 性 能 。 我 们 使 用 延迟 来 定义 一 些 
契约 ， 对 某 特 定 类 的 某 个 脱 管 的 实例 ， 知 道 有 哪些 数据 是 可 以 使 用 的 。 


19.1.1. 操作 延迟 加 载 的 关联 


默认 情况 下 ，Hibernate 3 对 集合 使 用 延迟 select 抓 取 ， 对 返回 单 值 的 关联 使 用 延迟 
代理 抓 取 。 对 几乎 是 所 有 的 应 用 而 言 ， 其 绝 大 多 数 的 关联 ， 这 种 策略 都 是 有 效 的 。 
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注意 :假若 你 设置 了 hibernate.default_batch fetch size ,Hibernate 会 对 延迟 
加 载 采取 批量 抓 取 优化 措施 (这 种 优化 也 可 能 会 在 更 细 化 的 级 别 打开 ) 。 


然而 ， 你 必须 了 解 延迟 抓 取 带 来 的 一 个 问题 。 在 一 个 打开 的 Hibernate session 上 下 
文 之 外 调用 延迟 集合 会 导致 一 次 意外 。 比 如 : 


s = sessions.openSession(); 
Transaction tx = s.beginTransaction(); 


User u = (User) s.createQuery("from User u where u.name=:userNam 
e") 

.setString("userName", userName) .uniqueResult(); 
Map permissions = u.getPermissions(); 


tx.commit(); 
s.close(); 


Integer accessLevel = (Integer) permissions.get("accounts"); // 
Error! 


在 Session 关闭 后 ，permessions 集 合 将 是 未 实例 化 的 、 不 再 可 用 ， 因 此 无 法 正 
常 载 入 其 状态 。 Hibernate 对 脱 管 对 象 不 支持 延迟 实例 化 . 这 里 的 修改 方法 是 : 将 
permissions 读 取 数 据 的 代码 移 到 tx.commit() 之 前 。 


除 此 之 外 ， 通 过 对 关联 映射 指定 lazy="false" ,我 们 也 可 以 使 用 非 延迟 的 集合 或 
关联 。 但 是 ， 对 绝 大 部 分 集合 来 说 ， 更 推荐 使 用 延迟 方式 抓 取 数 据 。 如 果 在 你 的 对 
象 模型 中 定义 了 太 多 的 非 延迟 关联 ，Hibernate 最 终 几 乎 需要 在 每 个 事务 中 载 入 整个 
数据 库 到 内 存 中 ! 


但 是 ， 另 一 方面 ， 在 一 些 特殊 的 事务 中 ， 我 们 也 经 常 需 要 使 用 到 连接 抓 取 〈 它 本 身 
上 就 是 非 延 迟 的 ) ， 以 代替 查询 抓 取 。 下 面 我 们 将 会 很 快 明白 如 何 具 体 的 定制 
Hibernate 中 的 抓 取 策略 。 在 Hibernate3 中 ， 具 体 选 择 哪 种 抓 取 策 略 的 机 制 是 和 选择 
单 值 关联 或 集合 关联 相 一 致 的 。 


19.1.2. 调整 抓 取 策略 (Tuning fetch strategies ) 


查询 抓 取 (默认 的 ) 在 N+1 查 询 的 情况 下 是 极其 脆弱 的 ， 因 此 我 们 可 能 会 要 求 在 映 
射 文档 中 定义 使 用 连接 抓 取 : 


<set name="permissions" 
fetch="join"> 
<key column="userId"/> 
<one-to-many class="Permission"/> 
</set 


<many-to-one name="mother" class="Cat" fetch="join"/> 


在 映射 文档 中 定义 的 抓 取 策略 将 会 对 以 下 列表 条 目 产生 影响 : 
e 通过 get() 或 load() 方法 取得 数据 。 
e@ 只 有 在 关联 之 问 进行 导航 时 ， 才 会 隐 式 的 取得 数据 。 
e@ 条件 查询 
e 使 用 了 subselect 抓 取 的 HQL 查 询 


不 管 你 使 用 哪 种 抓 取 策 略 ， 定 义 为 非 延迟 的 类 图 会 被 保证 一 定 装载 入 内 存 。 注 意 这 
可 能 意味 着 在 一 条 HQL 查 询 后 紧 跟着 一 系列 的 查询 。 


通常 情况 下 ， 我 们 并 不 使 用 映射 文档 进行 抓 取 策 略 的 定制 。 更 多 的 是 ， 保 持 其 默认 
值 ， 然 后 在 特定 的 事务 中 ， 使 用 HQL 的 左 连接 抓 取 (left join fetch) 对 其 进 
行 重 载 。 这 将 通知 Hibernate 在 第 一 次 查询 中 使 用 外 部 关联 (outer join ) ， 直 接 得 
到 其 关联 数据 。 在 条 件 查询 API 中 ， 应 该 调用 

setFetchMode(FetchMode.JOIN) 7&4) ° 


也 许 你 喜欢 仅仅 通过 条 件 查询 ， 就 可 以 改变 get() 或 load() 语句 中 的 数据 抓 
取 策 略 。 例 如 : 


User user = (User) session.createCriteria(User.class) 
.setFetchMode("permissions", FetchMode. JOIN) 
.add( Restrictions.idEq(userId) ) 
.uniqueResult(); 


(这 就 是 其 他 ORM 解 决 方案 的 " 抓 取 计划 (fetch plan)’ # Hibernate F 9 =F Ht o ) 
截然 不 同 的 一 种 避免 N+1 次 查询 的 方法 是 ， 使 用 二 级 缓存 。 
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19.1.3. 单 端 关联 代理 (Single-ended association 
proxies ) 


在 Hinerbate 中 ， 对 集合 的 延迟 抓 取 的 采用 了 自己 的 实现 方法 。 但 是 ， 对 于 单 端 关联 
的 延迟 抓 取 ， 则 需要 采用 其 他 不 同 的 机 制 。 单 端 关 联 的 目标 实体 必须 使 用 代理 ， 
Hihernate 在 运行 期 二 进 制 级 (通过 优异 的 CGLIB 库 ) ， 为 持久 对 象 实现 了 延迟 载 
入 代理 。 

默认 的 ，Hibernate3 将 会 为 所 有 的 持久 对 萌 产 生 代理 (在 启动 阶段 )， 然 后 使 用 他 
们 实现 多 对 一 (many-to-one) 关联 和 一 对 一 (one-to-one) 关联 的 延迟 抓 
取 。 

在 映射 文件 中 ， 可 以 通过 设置 proxy 属性 为 目标 class 声 明 一 个 接口 供 代 理 接 口 使 
用 。 默认 的 ，Hibernate 将 会 使 用 该 类 的 一 个 子 类 。 注意 : 被 代理 的 类 必须 实现 一 
个 至 少 包 可 见 的 默认 构造 函数 ， 我 们 建议 所 有 的 持久 类 都 应 拥有 这 样 的 构造 函数 


在 如 此 方式 定义 一 个 多 态 类 的 时 候 ， 有 许多 值得 注意 的 常见 性 的 问题 ， 例 如 : 


<class name="Cat" proxy="Cat"> 


</subclass> 
</class> 


首先 ， Cat 实例 永远 不 可 以 被 强制 转换 为 DomesticCat ,即使 它 本 身 就 
是 DomesticCat 实例 。 


Cat cat = (Cat) session.load(Cat.class, id); // instantiate a p 
roxy (does not hit the db) 


if ( cat.isDomesticCat() ) { // hit the db to i 
nitialize the proxy 

DomesticCat dc = (DomesticCat) cat; // Error! 
} 


其 次 ， 代 理 的 * == "可 能 不 再 成 立 。 


Cat cat = (Cat) session.load(Cat.class, id); // insta 
ntiate a Cat proxy 
DomesticCat dc = 

(DomesticCat) session.load(DomesticCat.class, id); //a 
cquire new DomesticCat proxy! 
System.out.println(cat==dc) ; // false 


虽然 如 此 ， 但 实际 情况 并 没有 看 上 去 那么 糟 薰 。 虽 然 我 们 现在 有 两 个 不 同 的 引用 ， 
分 别 指向 这 两 个 不 同 的 代理 对 象 ， 但 实际 上 ， 其 底层 应 该 是 同一 个 实例 对 象 : 


cat.setWeight(11.0); // hit the db to initialize the proxy 
System.out.println( dc.getWeight() ); // 11.0 


第 三 ， 你 不 能 对 “final 类 ”或 “具有 final 方 法 的 类 "使 用 CGLIB 代 理 。 


最 后 ， 如 果 你 的 持久 化 对 象 在 实例 化 时 需要 东 些 次 资源 (例如 ， 在 实例 化 方法 、 默 认 

构造 方法 中 ) ， 那 么 代理 对 象 也 同样 需要 使 用 这 些 资源 。 实 际 上 ， 代 理 类 是 持久 化 

类 的 子 类 。 

这 些 问题 都 源 于 Java 的 单 根 继承 模型 的 天 生 限制 。 如 果 你 希望 避免 这 些 问题 ， 那 么 

你 的 每 个 竺 久 化 类 必须 实现 一 个 接口 ， 在 此 接口 中 已经 声明 了 其 业务 方法 。 然 后 ， 
你 需要 在 映射 文档 中 再 指定 这 些 接口 。 例 如 : 


<class name="CatImpl" proxy="Cat"> 


</subclass> 
</class> 


这 里 CatImpl 实现 了 cat 接口 ， DomesticCatImpl 实现 DomesticCat 接 
ao Æ load() `œ iterate() 方法 中 就 会 返回 Cat 和 Domesticcat 的 代理 对 
Ro (注意 list() 并 不 会 返回 代理 对 象 。) 


Cat cat = (Cat) session.load(CatImpl.class, catid); 

Iterator iter = session.iterate("from CatImpl as cat where cat.n 
ame='fritz'"); 

Cat fritz = (Cat) iter.next(); 


这 里 ， 对 象 之 间 的 关系 也 将 被 延迟 载 入 。 这 就 意味 着 ， 你 应 该 将 属性 声明 
为 Cat ， 而 不 是 CatImpl ° 


哩 是 ， 在 有 些 方法 中 是 不 需要 使 用 代理 的 。 例 如 : 
e equals() 方法 ， 如 果 持 久 类 没有 重 载 equals() 方法 。 
e hashcode() 方法 ， 如 果 持 久 类 没有 重 载 hashCode() 方法 。 
e 标志 符 的 getter 方 法 。 
Hibernate 将 会 识别 出 那些 重 载 了 equals() 、 或 hashCode() 方法 的 持久 化 类 。 


若 选 择 lazy="no-proxy" 而 非 默 认 的 lazy="proxy" ， 我 们 可 以 避免 类 型 转换 
带 来 的 问题 。 然 而 ， 这 样 我 们 就 需要 编译 期 字 节 码 增强 ， 并 且 所 有 的 操作 都 会 导致 
立刻 进行 代理 初始 化 。 


19.1. 抓 取 策 略 (Fetching strategies) 
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19.1.4. 实例 化 集合 和 代理 (Initializing 
collections and proxies ) 


在 Session 范围 之 外 访问 未 初始 化 的 集合 或 代理 ，Hibernate 将 会 抛 
出 LazyInitializationException 异常 。 也 就 是 说 ， 在 分 离 状态 下 ， 访 问 一 个 
实体 所 拥有 的 集合 ， 或 者 访问 其 指向 代理 的 属性 时 ， 会 引发 此 异常 。 


有 时 候 我 们 需要 保证 某 个 代理 或 者 集合 在 Session 关 闭 前 就 已 经 被 初始 化 了 。 当 
然 ， 我 们 可 以 通过 强行 调用 cat.getSex() 或 者 cat.getKittens().size() 之 
类 的 方法 来 确保 这 一 点 。 但 是 这 样 的 程序 会 造成 读者 的 疑惑 ， 也 不 符合 通常 的 代码 
规范 。 

静态 方法 Hibernate.initialized() 为 你 的 应 用 程序 提供 了 一 个 便捷 的 途径 来 
延迟 加 载 集合 或 代理 。 只 要 它 的 Session 处 于 open 状 

Æ> Hibernate.initialize(cat) 将 会 为 cat 强 制 对 代理 实例 化 。 同 

样 ， Hibernate.initialize( cat.getKittens() ) 对 kittens 的 集合 具有 同样 
的 功能 。 


还 有 另外 一 种 选择 ， 就 是 保持 Session 一 直 处 于 open 状 态 ， 直 到 所 有 需要 的 集合 
或 代理 都 被 载 入 。 在 某 些 应 用 架构 中 ， 特 别 是 对 于 那些 使 用 Hibernate 进 行 数据 访 
问 的 代码 ， 以 及 那些 在 不 同 应 用 层 和 不 同 物理 进程 中 使 用 Hibernate 的 代码 。 在 集 
合 实例 化 时 ， 如 何 保 证 Session 处 于 open 状 态 经 常会 是 一 个 问题 。 有 两 种 方法 可 
以 解决 此 问题 : 


e 在 一 个 基于 Web 的 应 用 中 ， 可 以 利用 servlet 过 滤器 (filter) > AA PAR 
(request) 结束 、 页 面 生 成 结束 时 关闭 Session (这 里 使 用 了 在 展示 层 保 
持 打 开 Session 模 式 (Open Session in View) ) ， 当 然 ， 这 将 依赖 于 应 用 框 
架 中 异常 需要 被 正确 的 处 理 。 在 返回 界面 给 用 户 之 前 ， 乃 至 在 生成 界面 过 程 中 
发 生 异 常 的 情况 下 ， 正 确 关 闭 Session 和 结束 事务 将 是 非常 重要 的 ， 请 参见 
Hibernate wiki 上 的 "Open Session in View" 模 式 ， 你 可 以 找到 示例 。 


e 在 一 个 拥有 单独 业务 层 的 应 用 中 ， 业 务 层 必须 在 返回 之 前 ， 为 web 层 “准备 "好 
其 所 需 的 数据 集合 。 这 就 意味 着 业务 层 应 该 载 入 所 有 表现 层 /web 层 所 需 的 数 
据 ， 并 将 这 些 已 实例 化 完毕 的 数据 返回 。 通 常 ， 应 用 程序 应 该 为 Web 层 所 需 的 
每 个 集合 调用 Hibernate.initialize() (这 个 调用 必须 发 生 咱 session 关 闭 
之 前 ) ; 或 者 使 用 带 有 FETCH M4) > X FetchMode.JOIN 的 Hibernate 查 
询 ， 事 先 取得 所 有 的 数据 集合 。 如 果 你 在 应 用 中 使 用 了 Cormrmanad 模 式 ， 代 替 
Session Facade ， 那 么 这 项 任务 将 会 变 得 简单 的 多 。 


e 你 也 可 以 通过 merge() 或 lock() 方法 ， 在 访问 未 实例 化 的 集合 (或 代理 ) 
之 前 ， 为 先前 载 入 的 对 象 绑 定 一 个 新 的 Session 。 显然，Hibernate 将 不 
会 ， 也 不 应 该 自动 完成 这 些 任务 ， 因 为 这 将 引入 一 个 特殊 的 事务 语义 。 

有 时 候 ， 你 并 不 需要 完全 实例 化 整个 大 的 集合 ， 仅 需要 了 解 它 的 部 分 信息 (例如 其 
大 小 ) 、 或 者 集合 的 部 分 内 容 。 


你 可 以 使 用 集合 过 滤器 得 到 其 集合 的 大 小 ， 而 不 必 实 例 化 整个 集合 : 


Æ 
分 


( (Integer) s.createFilter( collection, "select count(*)" ).list 
().get(0) ).intValue() 


这 里 的 createFilter() 方法 也 可 以 被 用 来 有 效 的 抓 取 集合 的 部 分 内 容 ， 而 无 需 
实例 化 整个 集合 : 


s.createFilter( lazyCollection, "").setFirstResult(0).setMaxResu 
1ts(10).list(); 


19.1.5. 使 用 批量 抓 取 (Using batch fetching) 


Hibernate 可 以 充分 有 效 的 使 用 批量 抓 取 ， 也 就 是 说 ， 如 果 仅 一 个 访问 代理 (或 集 
A) ， 那 么 Hibernate 将 不 载 入 其 他 未 实例 化 的 代理 。 批 量 抓 取 是 延迟 查询 抓 取 的 
优化 方案 ， 你 可 以 在 两 种 批量 抓 取 方 案 之 间 进 行 选择 : 在 类 级 别 和 集合 级 别 。 


类 /实体 级 别 的 批量 抓 取 很 容易 理解 。 假 设 你 在 运行 时 将 需要 面 对 下 面 的 问题 : 你 在 
一 个 Session 中 载 入 了 25 个 cat 实例 ， 每 个 cat 实例 都 拥有 一 个 引用 成 

员 owner ， 其 指向 Person > m Person 类 是 代理 ， 同 时 lazy="true" ° 如 
果 你 必须 遍历 整个 cats 集 合 ， 对 每 个 元 素 调用 getowner() 方法 ，Hibernate 将 会 
默认 的 执行 25 次 SELECT 查询 ， 得 到 其 owner 的 代理 对 象 。 这 时 ， 你 可 以 通过 在 映 
射 文件 的 Person 属性 ， 显 式 声明 batch-size ， 改 变 其 行为 : 


<class name="Person" batch-size="10">...</class> 


随 之 ，Hibernate 将 只 需要 执行 三 次 查询 ， 分 别 为 10、10、5。 


你 也 可 以 在 集合 级 别 定义 批量 抓 取 。 例 如 ， 如 果 每 个 Person 都 拥有 一 个 延迟 载 入 
的 cats 集合 ， 现 在 ， Sesssion 中 载 入 了 10 个 person 对 象 ， 遍 历 person 集 合 将 
会 引起 10 次 SELECT 查询 ， 每 次 查询 都 会 调用 getCats() 方法 。 如 果 你 

在 Person 的 映射 定义 部 分 ， 允 许 对 cats 批量 抓 取 , 那么 ，Hibernate 将 可 以 预先 
抓 取 整个 集合 。 请 看 例子 : 


<class name="Person"> 
<set name="cats" batch-size="3"> 


</set> 
</class> 


如 果 整 个 的 batch-size 是 3 (Bik?) ， 那 么 Hibernate 将 会 分 四 次 执 
行 SELECT 查询 ， 按 照 3、3、3、1 的 大 小 分 别 载 入 数据 。 这 里 的 每 次 载 入 的 数据 
量 还 具体 依赖 于 当前 Session 中 未 实例 化 集合 的 个 数 。 


如 果 你 的 模型 中 有 网 套 的 树 状 结构 ， 例 如 典型 的 帐 单一 原料 结构 (bil-of-materials 
pattern) ， 集 合 的 批量 抓 取 是 非常 有 用 的 。 (尽管 在 更 多 情况 下 对 树 进行 读 取 时 ， 
RES (nested set) 或 原料 路 径 (materialized path) (xx) 是 更 好 的 解决 方 

法 。) 


19.1.6. 使 用 子 查 询 抓 取 〈Using subselect 
fetching ) 
假若 一 个 延迟 集合 或 单 值 代理 需要 抓 取 ，Hibernate 会 使 用 一 个 subselect 重 新 运行 


原来 的 查询 ， 一 次 性 读 入 所 有 的 实例 。 这 和 批量 抓 取 的 实现 方法 是 一 样 的 ， 不 会 有 
破碎 的 加 载 。 


19.1.7. 使 用 延迟 属性 抓 取 〈Using lazy property 
fetching ) 


Hibernate3 对 单独 的 属性 支持 延迟 抓 取 ， 这 项 优化 技术 也 被 称 为 组 抓 取 (fetch 
groups) ° 请 注意 ， 该 技术 更 多 的 属于 市 场 特性 。 在 实际 应 用 中 ， 优 化 行 读 取 比 优 
化 列 读 取 更 重要 。 但 是 ， 仅 载 入 类 的 部 分 属性 在 某 些 特定 情况 下 会 有 用 ， 例 如 在 原 
有 表 中 拥有 几 百 列 数据 、 数 据 模 型 无 法 改动 的 情况 下 。 


可 以 在 映射 文件 中 对 特定 的 属性 设置 lazy ， 定 义 该 属性 为 延迟 载 入 


<class name="Document"> 
<id name="id"> 
<generator class="native"/> 
</id> 
<property name="name" not-null="true" length="50"/> 
<property name="Summary" not-null="true" length="200" lazy=" 
true"/> 
<property name="text" not-null="true" length="2000" lazy="tr 
ue" /> 
</class> 


属性 的 延迟 载 入 要 求 在 其 代码 构建 时 加 入 二 进 制 指示 指令 (bytecode 
instrumentation) ， 如 果 me 
这 些 属性 的 延迟 设置 ， 仍 然 将 其 直接 载 入 。 


你 可 以 在 Ant 的 Task 中 ， 进 行 如 下 定义 ， 对 持久 类 代码 加 入 "二进制 指令 。” 


<target name="instrument" depends="compile"> 
<taskdef name="instrument" classname="org.hibernate.tool.ins 
trument.InstrumentTask"> 
<classpath path="${jar.path}"/> 
<classpath path="${classes.dir}"/> 
<classpath refid="lib.class.path"/> 
</taskdef> 


<instrument verbose="true"> 
<fileset dir="${testclasses.dir}/org/hibernate/auction/m 


odel"> 
<include name="*.class"/> 
</fileset> 
</instrument> 


</target> 


还 有 一 种 可 以 优化 的 方法 ， 它 使 用 HQL 或 条 件 查 询 的 投影 (projection) 特性 ， 可 以 
避免 读 取 非 必要 的 列 ， 这 一 点 至 少 对 只 读 事务 是 非常 有 用 的 。 它 无 需 在 代码 构建 
时 “二 进 制 指令 ”处理 ， 因 此 是 一 个 更 加 值得 选择 的 解决 方法 。 


有 时 你 需要 在 HQL 中 通过 抓 取 所 有 属性 ， 强 行 抓 取 所 有 内 容 。 


19.2. 二 级 缓存 (The Second Level Cache) 


Hibernate 的 Session 在 事务 级 别 进 行 持 久 化 数据 的 缓存 操作 。 当然 ， 也 有 可 能 
分 别 为 每 个 类 (或 集合 )， 配 置 集群 、 或 JVM 级 别 ( SessionFactory 级 别 ) 的 缓存 。 
你 甚至 可 以 为 之 插入 一 个 集群 的 缓存 。 注 意 ， 绥 存 永 远 不 知道 其 他 应 用 程序 对 持久 
化 仓库 (数据库) 可 能 进行 的 修改 (即使 可 以 将 缓存 数据 设 定 为 定期 失效 ) © 


通过 在 hibernate.cache.provider_class 属性 中 指 

定 org.hibernate.cache.CacheProvider 的 某 个 实现 的 类 名 ,你 可 以 选择 让 
Hibernate 使 用 哪个 缓存 实现 。Hibernate 打 包 一 些 开源 缓存 实现 ， 提 供 对 它们 的 内 
置 支持 (MPR) 。 除 此 之 外 ， 你 也 可 以 实现 你 自己 的 实现 ， 将 它们 插入 到 系统 
中 。 注 意 ， 在 3.2 版 本 之 前 ， 默 认 使 用 EhCache 作为 缓存 实现 ， 但 从 3.2 起 就 不 再 这 
样 了 。 


表 19.1. 缓存 策略 提供 商 (Cache Providers) 


Cache Provider class Tyg 
Hashtable 
(not intended 
for org.hibernate.cache.HashtableCacheProvider memor 
production 
use) 
EHCache org. hibernate.cache.EhCacheProvider rata 
| 
OSCache org. hibernate.cache.OSCacheProvider oe 
| 
SwarmCache org. hibernate.cache.SwarmCacheProvider cluster¢ 
multica 
JBoss clusters 
ofg.hibernate.cache:. InreeCacherrovider j 
TreeCache g multica 


transac 


19.2.1. 24 RA (Cache mappings ) 
类 或 者 集合 映射 的 ”&1t;cache&gt; 元 素 " 可 以 有 下 列 形 式 : 


<Cache 
usage="transactional|read-write|nonstrict-read-write|read-on 


ly" 
region="RegionName" 
include="all1|non-lazy" 
/> 


usage (必须 ) 说 明了 缓存 的 策略 : transactional 、 read-write 、 
nonstrict-read-write 或 read-only ° 


region (可 选 , 默认 为 类 或 者 集合 的 名 字 (class or collection role name)) 指 
定 第 二 级 缓存 的 区 域名 (name of the second level cache region) 


include (可 选 ,默认 为 all) non-lazy 当 属 性 级 延迟 抓 取 打开 时 , 标 


© 记 为 lazy="true" 的 实体 的 属性 可 能 无 法 被 缓存 


另外 (首选 ?), 你 可 以 在 hibernate.cfg.xml 中 指定 &lt;class-cache&gt; 和 
&lt;collection-cache&gt; 元 素 。 


这 里 的 usage 属性 指明 了 缓存 并 发 策略 (cache concurrency strategy) ° 


19.2.2. 策略 : RAB (Strategy: read only) 


读 取 一 个 持久 化 类 的 实例 ， 而 无 需 对 其 修改 ， 那 么 就 可 以 对 


如 果 你 的 应 用 程序 只 需 
o 3 简单 ， 也 是 实用 性 最 好 的 方法 。 甚 至 在 集群 中 它 也 能 


其 进行 只 读 缓存 
完美 地 运作 。 


ba 3 
部 bas 
as 


<class name="eg.Immutable" mutable="false"> 
<cache usage="read-only"/> 


</class> 


19.2.3. 策略 : 读 / 写 缓存 (Strategy: read/write ) 


如 果 应 用 程序 需要 更 新 数据 ， 那 么 使 用 读 / 写 缓存 比较 合适 。 如 果 应 用 程序 要 
求 “序列 化 事务 "的 隔离 级 别 (serializable transaction isolation level) > MARAT 
能 使 用 这 种 缓存 策略 。 如果 在 JTA 环 境 中 使 用 缓存 ， 你 必须 指 

Æ hibernate.transaction.manager_lookup_class 属性 的 值 ， 通 过 它 ， 
Hibernate 才 能 知道 该 应 用 程序 中 JTA 的 TransactionManager 的 具体 策略 。 在 其 
它 环境 中 ， 你 必须 保证 在 Session,close() `X Session.disconnect() 调用 
前 ， 整 个 事务 已 经 结束 。 如 果 你 想 在 集群 环境 中 使 用 此 策略 ， 你 必须 保证 底层 的 
缓存 实现 支持 锁定 (locking)。Hibernate 内 置 的 缓存 策略 并 不 支持 锁定 功能 。 


<class name="eg.Cat" .... > 
<cache usage="read-write"/> 


<set name="kittens" ... > 
<cache usage="read-write"/> 


</set> 
</class> 


19.2.4. 策略 : 非 严 格 读 / 写 缓存 (Strategy: 
nonstrict read/write ) 


如 果 应 用 程序 只 偶尔 需要 更 新 数据 (也 就 是 说 ， 两 个 事务 同时 更 新 同一 记录 的 情况 
很 不 常见 ) ， 也 不 需要 十 分 严格 的 事务 隔离 ， 那 么 比较 适合 使 

用 非 严格 读 / 写 缓存 策略 。 如 果 在 JTA 环 境 中 使 用 该 策略 ， 你 必须 为 其 指 

定 hibernate.transaction.manager_lookup_class 属性 的 值 ， 在 其 它 环境 
中 ， 你 必须 保证 在 Session.close() 、 或 Session.disconnect() 调用 前 ， 整 
个 事务 已 经 结束 。 


19.2.5. 策略 :事务 缓存 (transactional) 


Hibernate 的 事务 缓存 策略 提供 了 全 事务 的 缓存 支持 ， 例 如 对 JBoss TreeCache 的 
支持 。 这 样 的 缓存 只 能 用 于 JTA 环 境 中 ， 你 必须 指定 为 

其 hibernate.transaction.manager_lookup_class 属性 。 

没有 一 种 缓存 提供 商 能 够 支持 上 列 的 所 有 缓存 并 发 策略 。 下 表 中 列 出 了 各 种 提供 
器 、 及 其 各 自 适 用 的 并 发 策略 。 


表 19.2. 各 种 缓存 提供 商 对 缓存 并 发 策略 的 支持 情况 (Cache Concurrency 


Strategy Support) 
Cache read: 有 read- transactional 
only read-write Write 

Hashtable (not intended 

for production use) ee yes ue 

EHCache yes yes yes 

OSCache yes yes yes 

SwarmCache yes yes 


JBoss TreeCache yes yes 


19.3. 管理 缓存 (Managing the caches) 


无 论 何 时 ， 当 你 给 save() ` update() 或 saveOrUpdate() 方法 传递 一 个 对 
象 时 ， 或 使 用 load() 、 get() `œ list() `œ iterate() 或 scroll() 方法 
获得 一 个 对 象 时 , 该 对 象 都 将 被 加 入 到 Session 的 内 部 缓存 中 。 


当 随 后 flush() 方 法 被 调用 时 ， 对 象 的 状态 会 和 数据 库 取得 同步 。 如 果 你 不 希望 此 同 
步 操作 发 生 ， 或 者 你 正 处 理 大 量 对 象 、 需 要 对 有 效 管理 内 存 时 ， 你 可 以 调 
用 evict() 方法 ， 从 一 级 缓存 中 去 掉 这 些 对 象 及 其 集合 。 


ScrollableResult cats = sess.createQuery("from Cat as cat").scro 
11(); //a huge result set 
while ( cats.next() ) { 

Cat cat = (Cat) cats.get(0); 

doSomethingWithACat(cat); 

sess.evict(cat); 


Session 还 提供 了 一 个 contains() 方法 ， 用 来 判断 某 个 实例 是 否 处 于 当前 session 
的 缓存 中 。 


如 若 要 把 所 有 的 对 象 从 session 缓 存 中 彻底 清除 ， 则 需要 调 
用 Session.clear() ° 


对 于 二 级 缓存 来 说 ， 在 SessionFactory 中 定义 了 许多 方法 ， 清 除 缓存 中 实例 、 
整个 类 、 集 合 实例 或 者 整个 集合 。 


sessionFactory.evict(Cat.class, catId); //evict a particular Cat 
sessionFactory.evict(Cat.class); //evict all Cats 
sessionFactory.evictCollection("Cat.kittens", catId); //evict a 
particular collection of kittens 
sessionFactory.evictCollection("Cat.kittens"); //evict all kitte 
n collections 


CacheMode 参数 用 于 控制 具体 的 Session 如 何 与 二 级 缓存 进行 交互 。 
e CacheMode .NORMAL - 从 二 级 缓存 中 读 、 写 数据 。 


e CacheMode.GET -从 二 级 缓存 中 读 取 数据 ， 仅 在 数据 更 新 时 对 二 级 缓存 写 数 
dE o 


CacheMode.PUT - 仅 向 二 级 缓存 写 数据 ， 但 不 从 二 级 缓存 中 读数 据 。 


CacheMode.REFRESH - 仅 向 二 级 缓存 写 数 据 ， 但 不 从 二 级 缓存 中 读数 据 。 通 
过 hibernate.cache.use_minimal_puts 的 设置 ， 强 制 二 级 缓存 从 数据 库 
中 读 取 数 据 ， 刷 新 缓存 内 容 。 


如 若 需 要 查看 二 级 缓存 或 查询 缓存 区 域 的 内 容 ， 你 可 以 使 用 统计 (Statistics) 
API ° 


Map cacheEntries = sessionFactory.getStatistics() 
.getSecondLevelCacheStatistics(regionName ) 
.getEntries(); 


此 时 ， 你 必须 手工 打开 统计 选项 。 可 选 的 ， 你 可 以 让 Hibernate 更 人 工 可 读 的 方式 维 
护 缓存 内 容 。 


hibernate.generate_statistics true 
hibernate.cache.use_structured_entries true 


19.4. £79224 (The Query Cache) 


查询 的 结果 集 也 可 以 被 缓存 。 只 有 当 经 常 使 用 同样 的 参数 进行 查询 时 ， 这 才 会 有 些 
用 处 。 要 使 用 查询 缓存 ， 首 先 你 必须 打开 它 : 


hibernate.cache.use_query_cache true 


该 设置 将 会 创建 两 个 缓存 区 域 - 一 个 用 于 保存 查询 结果 集 

( org.hibernate.cache.StandardQueryCache ); 另 一 个 则 用 于 保存 最 近 查 询 的 
一 系列 表 的 时 间 戳 ( org. hibernate.cache.UpdateTimestampsCache )° 请 注 

意 : 在 查询 缓存 中 ， 它 并 不 缓存 结果 集中 所 包含 的 实体 的 确切 状态 ; 它 只 缓存 这 些 
实体 的 标识 符 属性 的 值 、 以 及 各 值 类 型 的 结果 。 所 以 查询 缓存 通常 会 和 二 级 缓存 一 
起 使 用 。 


绝 大 多 数 的 查询 并 不 能 从 查询 缓存 中 受益 ， 所 以 Hibernate 黑 认 是 不 进行 查询 缓存 
的 。 如 若 需 要 进行 缓存 ， 请 调用 Query.setcacheable(true) 方法 。 这 个 调用 会 
让 查询 在 执行 过 程 中 时 先 从 缓存 中 查找 结果 ， 并 将 自己 的 结果 集 放 到 缓存 中 去 。 


如 果 你 要 对 查询 缓存 的 失效 政策 进行 精确 的 控制 ， 你 必须 调 
用 Query.setCacheRegion() 方法 ， 为 每 个 查询 指定 其 命名 的 缓存 区 域 。 


List blogs = sess.createQuery("from Blog blog where blog.blogger 
= :blogger") 

.setEntity("blogger", blogger) 

.setMaxResults(15) 

. setCacheable( true) 

.setCacheRegion("frontpages" ) 

ALISE)? 


如 果 查 询 需 要 强行 刷新 其 查询 缓存 区 域 ， 那 么 你 应 该 调 

用 Query.setCacheMode(CacheMode.REFRESH) 方法 。 这 对 在 其 他 进程 中 修改 底 
层 数据 〈 例 如 ， 不 通过 Hibernate 修 改 数据 ) ， 或 对 那些 需要 选择 性 更 新 特定 查询 结 
果 集 的 情况 特别 有 用 。 这 是 对 SessionFactory.evictQueries() 的 更 为 有 效 的 

替代 方案 ， 同 样 可 以 清除 查询 缓存 区 域 。 


19.5. 理解 集合 性 能 (Understanding Collection 
performance ) 


前 面 我 们 已 经 对 集合 进行 了 足够 的 讨论 。 本 段 中 ， 我 们 将 着 重 讲述 集合 在 运行 时 的 
事宜 。 


19.5.1. 分 类 (Taxonomy) 


Hibernate 定 义 了 三 种 基本 类 型 的 集合 : 
o 值 数据 集合 
e 一 对 多 关联 
e 多 对 多 关联 


这 个 分 类 是 区 分 了 不 同 的 表 和 外 键 关 系 类 型 ， 但 是 它 没有 告诉 我 们 关系 模型 的 所 有 
内 容 。 要 完全 理解 他 们 的 关系 结构 和 性 能 特点 ， 我 们 必须 同时 考虑 “用 于 Hibernate 
更 新 或 删除 集合 行 数据 的 主键 的 结构 "。 因此 得 到 了 如 下 的 分 类 : 


© 有 序 集合 类 
e ZA (sets) 
e é, (bags) 


所 有 的 有 序 集合 类 (maps, lists, arrays) 都 拥有 一 个 由 &1lt;key&gt; 和 

&lt;index&gt; 组 成 的 主键 。 这 种 情况 下 集合 类 的 更 新 是 非常 高 效 的 主键 已 
经 被 有 效 的 索引 ， 因 此 当 Hibernate 试 图 更 新 或 删除 一 行 时 ， 可 以 迅速 找到 该 行 数 
据 。 


集合 (sets) 的 主键 由 &RLtikey&gt; 和 其 他 元 素 字 段 构成 。 对 于 有 些 元 素 类 型 来 

说 ， 这 很 低 效 ， 特 别 是 组 合 元 素 或 者 大 文本 、 大 二 进 制 字段 ; 数据 库 可 能 无 法 有 效 
的 对 复杂 的 主键 进行 索引 。 另 一 方面 ， 对 于 一 对 多 、 多 对 多 关联 ， 特 别 是 合成 的 标 
识 符 来 说 ， 集 合 也 可 以 达到 同样 的 高 效 性 能 。 ( 附注 : 如 果 你 希 

望 SchemaExport 为 你 的 &1t;set&gt; 创建 主键 ， 你 必须 把 所 有 的 字段 都 声明 
为 not-null="true" œ) 


&lt;idbag&gt; 映射 定义 了 代理 键 ， 因 此 它 总 是 可 以 很 高 效 的 被 更 新 。 事 实 上 ， 
&lt;idbag&gt; 拥有 着 最 好 的 性 能 表现 。 


Bag 是 最 差 的 。 因 为 bag 人 允许 重复 的 元 素 值 ， 也 没有 索引 字段 ， 因 此 不 可 能 定义 主 
键 。Hibernate 无 法 判断 出 重复 的 行 。 当 这 种 集合 被 更 改 时 ，Hibernate 将 会 先 完整 
地 移 除 (通过 一 个 (in a single DELETE )) 整个 集合 ， 然 后 再 重新 创建 整个 集合 。 
因此 Bag 是 非常 低 效 的 。 

请 注意 : 对 于 一 对 多 关联 来 说 ，“ 主 键 " 很 可 能 并 不 是 数据 库 表 的 物理 主键 。 但 就 算 
在 此 情况 下 ， 上 面 的 分 类 仍然 是 有 用 的 。 ( 它 仍 然 反 映 了 Hibernate 在 集合 的 各 数据 
行 中 是 如 何 进行 “定位 ?的 。) 





19.5.2. Lists, maps 和 sets 用 于 更 新 效率 最 高 


根据 我 们 上 面 的 讨论 ， 显 然 有 序 集合 类 型 和 大 多 数 set 都 可 以 在 增加 、 删 除 、 修 改元 
素 中 拥有 最 好 的 性 能 。 


可 论证 的 是 对 于 多 对 多 关联 、 值 数据 集合 而 言 ， 有 序 集合 类 比 集合 (set) 有 一 个 好 
处 。 因 为 set 的 内 在 结构 ， 如 果 "“ 改 变 ” 了 一 个 元 素 ，Hibernate 并 不 

会 更 新 (UPDATE) 这 一 行 。 对 于 Set 来 说 ， 只 有 

在 插入 (INSERT) 和 删除 (DELETE) 操作 时 “改变 " 才 有 效 。 再 次 强调 : 这 段 讨 
论 对 “一 对 多 关联 ?并 不 适用 。 


注意 到 数组 无 法 延迟 载 入 ， 我 们 可 以 得 出 结论 ，list map 和 idbags 是 最 高 效 的 ( 非 
反 向 ) 集合 类 型 ，set 则 紧 随 其 后 。 在 Hibernate 中 ，set 应 该 时 最 通用 的 集合 类 型 ， 
这 时 因为 “set” 的 语义 在 关系 模型 中 是 最 自然 的 。 


但 是 ， 在 设计 良好 的 Hibernate 领 域 模型 中 ， 我 们 通常 可 以 看 到 更 多 的 集合 事实 上 是 
带 有 inverse="true" 的 一 对 多 的 关联 。 对 于 这 些 关联 ， 更 新 操作 将 会 在 多 对 一 
的 这 一 端 进行 处 理 。 因 此 对 于 此 类 情况 ， 无 需 考 虑 其 集合 的 更 新 性 能 。 


19.5.3. Bag 和 list 是 反 向 集合 类 中 效率 最 高 的 


在 把 Dag 扔 进 水 沟 之 前 > 你 必须 了 解 ， 在 一 种 情况 下 ，bag 的 性 能 (包括 list) 要 比 set 
高 得 多 : 对 于 指明 了 inverse="true" 的 集合 类 (比如 说 ， 标 准 的 双向 的 一 对 多 
关联 ) ， 我 们 可 以 在 未 初始 化 (fetch) 包 元 素 的 情况 下 直接 向 bag 或 list 添 加 新 元 素 ! 
这 是 aie Collection.add() ) 或 者 Collection.addAll() 方法 ec 或 者 List 
返回 true (这 点 与 与 Set 不 同 ) 。 因 此 对 于 下 面 的 相同 代码 来 说 ， 速 度 会 快 得 


aK 


H 


Parent p = (Parent) sess.load(Parent.class, id); 
Child c = new Child(); 
c.setParent(p); 
p.getChildren().add(c); //no need to fetch the collection! 
sess.flush(); 


19.5.4. 一 次 性 删除 (One shot delete ) 


偶尔 的 ， 逐 个 删除 集合 类 中 的 元 素 是 相当 低 效 的 。Hibernate 并 没 那 么 策 ， 如 果 你 
想 要 把 整个 集合 都 删除 (比如 说 调用 list.clear()) ，Hibernate 只 需要 一 个 DELETE 
就 搞定 了 。 

假设 我 们 在 一 个 长 度 为 20 的 集合 类 中 新 增加 了 一 个 元 素 ， 然 后 再 删除 两 个 。 
Hibernate 会 安排 一 条 INSERT 语句 和 两 条 DELETE 724) (除非 集合 类 是 一 个 
bag)。 这 当然 是 显而易见 的 。 

但 是 ， 假 设 我 们 删除 了 18 个 数据 ， 只 剩 下 2 个 ， 然 后 新 增 3 个 。 则 有 两 种 处 理 方 式 : 
e 逐一 的 删除 这 18 个 数据 ， 再 新 增 三 个 ; 

e。 删除 整个 集合 类 (RA—4A4DELETE 4) ， 然 后 增加 5 个 数据 。 


Hibernate 还 没 那 各 聪明 ， 知 道 第 二 种 选择 可 能 会 比较 快 。 (也 许 让 Hibernate 不 这 
么 聪明 也 是 好 事 ， 否 则 可 能 会 引发 意外 的 “数据 库 触 发 器 "之 类 的 问题 。) 


幸运 的 是 ， 你 可 以 强制 使 用 第 二 种 策略 。 你 需要 取消 原来 的 整个 集合 类 ( 解 除 其 引 
A) ， 然 后 再 返回 一 个 新 的 实例 化 的 集合 类 ， 只 包含 需要 的 元 素 。 有 些 时 候 这 是 非 
常 有 用 的 。 


显然 ， 一 次 性 删除 并 不 适用 于 被 映射 为 inverse="true" 的 集合 。 


19.6. 监测 性 能 (Monitoring performance ) 


没有 监测 和 性 能 参数 而 进行 优化 是 毫 无 意义 的 。Hibernate 为 其 内 部 操作 提供 了 一 系 
列 的 示意 图 ， 因 此 可 以 从 每 个 SessionFactory 抓 取 其 统计 数据 。 


19.6.1. 监测 SessionFactory 


你 可 以 有 两 种 方式 访问 SessionFactory 的 数据 记录 ， 第 一 种 就 是 自己 直接 调用 
sessionFactory.getStatistics() 方法 读 取 、 显 示 统计 数据 。 


此 外 ， 如 果 你 打开 StatisticsService MBean 选 项 ， 那 么 Hibernate 则 可 以 使 用 
JMX 技 术 发 布 其 数据 记录 。 你 可 以 让 应 用 中 所 有 的 SessionFactory 同时 共享 一 
个 MBean， 也 可 以 每 个 SessionFactory 分 配 一 个 MBean。 下 面 的 代码 即 是 其 演示 
代码 : 


// MBean service registration for a specific SessionFactory 
Hashtable tb = new Hashtable(); 

tb.put("type", "statistics"); 

tb.put("sessionFactory", "myFinancialApp"); 

ObjectName on = new ObjectName("hibernate", tb); // MBean object 
name 


StatisticsService stats = new StatisticsService(); // MBean impl 
ementation 

stats.setSessionFactory(sessionFactory); // Bind the stats to a 
SessionFactory 

server.registerMBean(stats, on); // Register the Mbean on the se 
rver 


// MBean service registration for all SessionFactory's 

Hashtable tb = new Hashtable(); 

tb.put("type", “statistics” )> 

tb.put("sessionFactory", "all"); 

ObjectName on = new ObjectName("hibernate", tb); // MBean object 
name 


StatisticsService stats = new StatisticsService(); // MBean impl 
ementation 

server.registerMBean(stats, on); // Register the MBean on the se 
rver 


TODO : 仍 需要 说 明 的 是 : 在 第 一 个 例子 中 ， 我 们 直接 得 到 和 使 用 MBean ; 而 在 第 
二 个 例子 中 ， 在 使 用 MBean 之 前 我 们 则 需要 给 出 SessionFactory 的 JNDI 名 ， 使 

用 hibernateStatsBean.setSessionFactoryJNDIName("my/JNDI/Name") 得 到 
SessionFactory， 然 后 将 MBean 保 存 于 其 中 。 


你 可 以 通过 以 下 方法 打开 或 关闭 SessionFactory 的 监测 功能 : 


e 在 配置 期 间 ， 将 hibernate.generate_statistics 设置 
为 true 或 false ; 


e 在 运行 期 间 ， 则 可 以 可 以 通 
过 sf.getStatistics().setStatisticsEnabled(true) 
或 hibernateStatsBean.setStatisticsEnabled(true) 


你 也 可 以 在 程序 中 调用 clear() 方法 重 置 统计 数据 ， 调 用 logsummary() 在 日 
志 中 记录 (info 级 别 ) 其 总 结 。 


19.6.2. 数据 记录 (Metrics ) 


Hibernate 提 供 了 一 系列 数据 记录 ， 其 记录 的 内 容 包括 从 最 基本 的 信息 到 与 具体 场景 
的 特殊 信息 。 所 有 的 测量 值 都 可 以 由 Statistics 接口 进行 访问 ， 主 要 分 为 三 
类 : 
e 使 用 Session 的 普通 数据 记录 ， 例 如 打开 的 Session 的 个 数 、 取 得 的 JDBC 的 
连接 数 等 ; 


。 实体、 集合、 查询 、 缓 存 等 内 容 的 统一 数据 记录 
。 和 具体 实体 、 集 合 、 查 询 、 缓 存 相 关 的 详细 数据 记录 


例如 : 你 可 以 检查 缓存 的 命中 成 功 次 数 ， 缓 存 的 命中 失败 次 数 ， 实 体 、 集 合 和 查询 
的 使 用 概率 ， 查 询 的 平均 时 间 等 。 请 注意 Java 中 时 间 的 近似 精度 是 毫 不 
Hibernate 的 数据 精度 和 具体 的 JVM 有 关 ， 在 有 些 平 台 上 其 精度 甚至 只 能 精确 到 10 
秒 。 


你 可 以 直接 使 用 getter 方 法 得 到 全 局 数据 记录 (例如 ， 和 具体 的 实体 、 人 集合、 缓存 
区 无 关 的 数据 ) ， 你 也 可 以 在 具体 查询 中 通过 标记 实体 名 、 或 HQL、SQL 语 句 得 到 
某 实 体 的 数据 记录 。 请 参考 Statistics 、 EntityStatistics 、 
CollectionStatistics ` SecondLevelCacheStatistics ` 

和 QueryStatistics 的 API 文 档 以 抓 取 更 多 信息 。 下 面 的 代码 则 是 个 简单 的 例 
Fr 


È 


ò o 


Statistics stats = HibernateUtil.sessionFactory.getStatistics(); 


double queryCacheHitCount 
double queryCacheMissCount 
double queryCacheHitRatio = 
queryCacheHitCount / (queryCacheHitCount + queryCacheMissCount 


); 


log.info("Query Hit ratio:" + queryCacheHitRatio); 


stats.getQueryCacheHitCount(); 
stats.getQueryCacheMissCount(); 


EntityStatistics entityStats = 
stats.getEntityStatistics( Cat.class.getName() ); 
long changes = 
entityStats.getInsertCount() 
+ entityStats.getUpdateCount ( ) 
+ entityStats.getDeleteCount(); 
log.info(Cat.class.getName() + " changed " + changes + "times" 


); 


如 果 你 想得到 所 有 实体 、 集 合 、 查 询 和 缓存 区 的 数据 ， 你 可 以 通过 以 下 方法 获得 实 
体 、 集 合 、 查 询 和 缓存 区 列表 : getQueries() ` getEntityNames() ` 
getCollectionRoleNames() 和 getSecondLevelCacheRegionNames() ° 


19.6. 监测 性 能 (Monitoring performance ) 
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第 20 = 工具 箱 指 南 


目录 


e 20.1. Schema 自动 生成 (Automatic schema generation ) 

20.1.1. 对 Schema 定制 化 (Customizing the schema) 

20.1.2. 运行 该 工具 

20.1.3. 属性 (Properties) 

20.1.4. 使 用 Ant(Using Ant) 

20.1.5. 对 schema 的 增 量 更 新 (Incremental schema updates) 
20.1.6. 用 Ant 来 增 量 更 新 Schema(Using Ant for incremental schema 
updates) 

o 20.1.7. Schema 4 

o 20.1.8. 使 用 Ant 进 行 schema 校 验 


可 以 通过 一 系列 Eclipse 插件 、 命 令 行 工 具 和 Ant 任 务 来 进行 与 Hibernate 关 联 的 转 
换 。 


O O O O 0 0 


除了 Ant 任 务 外 ， 当 前 的 Hibernate Tools 也 包含 了 Eclipse IDE 的 插件 ， 用 于 与 现存 
数据 库 的 北向 工程 。 


e Mapping Editor: Hibernate XML 映射 文件 的 编辑 器 ， 支 持 自动 完成 和 语法 高 
。 它 也 支持 对 类 名 和 属性 /字段 名 的 语义 自动 完成 ， 比 通常 的 XML 编辑 器 方便 
Toe 


a Chr 


e Console: Console 是 Eclipse 的 一 个 新 视图 。 除 了 对 你 的 console 配 置 的 树 状 概 
览 ， 你 还 可 以 获得 对 你 持久 化 类 及 其 关联 的 交互 式 视图 。Console 允 许 你 对 数 
据 库 执行 HQL 查 询 ， 并 直接 在 Eclipse 中 浏览 结果 。 


e Development Wizards: 在 Hibernate Eclipse tools 中 还 提供 了 几 个 向 导 ; 你 可 
以 用 向 导 快 速生 成 Hibernate 配置 文件 (cfg.xml) ， 你 甚至 还 可 以 同 现存 的 数 
据 库 Schema 中 反 向 工程 出 POJO 源 代码 与 Hibernate 映射 文件 。 反 向 工程 支持 
可 定制 的 模版 。 


e Ant Tasks: 
要 得 到 更 多 信息 ， 请 查阅 Hibernate Tools 包 及 其 文档 。 


同时 ，Hibernate 主 发 行 包 还 附带 了 一 个 集成 的 工具 ( 它 甚 至 可 以 在 Hibernate“ 内 
部 "快速 运行 ) SchemaExport ， 也 就 是 hbm2ddl ° 


20.1. Schema 自动 生成 (Automatic schema 
generation ) 

可 以 从 你 的 映射 文件 使 用 一 个 Hibernate 工 具 生 成 DDL。 生成 的 Schema 包含 有 对 实 
休 和 集合 类 表 的 完整 性 引用 约束 (主键 和 外 键 ) 。 涉 及 到 的 标示 符 生 成 器 所 需 的 表 
和 sequence 也 会 同时 生成 。 


在 使 用 这 个 工具 的 时 候 ， 你 必须 通过 hibernate.dialet 属性 指定 一 个 
SQL 方言 (Dialet) ， 因 为 DDL 是 与 供应 商 高 度 相关 的 。 


首先 ， 要 定制 你 的 映射 文件 ， 来 改善 生成 的 Schema。 


20.1.1. 对 schema 定 制 化 (Customizing the 
schema) 


很 多 Hibernate 映 射 元 素 定义 了 可 选 的 length ` precision XA scale Æ 
性 。 你 可 以 通过 这 个 属性 设置 字段 的 长 度 、 精 度 、 小 数 点 位 数 。 


<property name="zip" length="5"/> 


<property name="balance" precision="12" scale="2"/> 


有 些 tag 还 接受 not-null 属性 (用 来 在 表 字 段 上 生成 NOT NULL 约束 ) 
和 unique 属性 (用 来 在 表 字 段 上 生成 UNIQUE 约束 ) © 


<many-to-one name="bar" column="barId" not-null="true"/> 


<element column="serialNumber" type="long" not-null="true" uniqu 
e="true"/> 


unique-key 属性 可 以 对 成 组 的 字段 指定 一 个 唯一 键 约束 (Unique key 
constraint)。 目 前 ， unique-key 属性 指定 的 值 在 生成 DDL 时 并 不 会 被 当 作 这 个 约 
束 的 名 字 ， 它 们 只 是 在 用 来 在 映射 文件 内 部 用 作 区 分 的 。 


<many-to-one name="org" column="orgId" unique-key="OrgEmployeeld 
u7 
<property name="employeeId" unique-key="OrgEmployee"/> 


index 属性 会 用 对 应 的 字段 (一 个 或 多 个 ) 生成 一 个 index, 它 指出 了 这 个 index 的 
名 字 。 如 果 多 个 字段 对 应 的 index 名 字 相 同 ， 就 会 生成 包含 这 些 字 段 的 index。 


<property name="lastName" index="CustName"/> 
<property name="firstName" index="CustName"/> 


foreign-key 属性 可 以 用 来 覆盖 任何 生成 的 外 键 约 束 的 名 字 。 


<many-to-one name="bar" column="barId" foreign-key="FKFooBar"/> 


很 多 映射 元 素 还 接受 &lt;coLlumn&gt; 子 元 素 。 这 在 定义 跨越 多 字段 的 类 型 时 特 
别 有 用 G 


<property name="name" type="my .customtypes .Name"/> 

<column name="last" not-null="true" index="bar_idx" length=" 
30"/> 

<column name="first" not-null="true" index="bar_idx" length= 
"20"/> 

<column name="initial"/> 
</property> 


default 属性 为 字段 指定 一 个 默认 值 (在 保存 被 映射 的 类 的 新 实例 之 前 ， 你 应 该 
将 同样 的 值 赋 于 对 应 的 属性 ) 。 


<property name="credits" type="integer" insert="false"> 
<column name="credits" default="10"/> 
</property> 


<version name="version" type="integer" insert="false"> 
<column name="version" default="0"/> 
</property> 


sql-type 属性 允许 用 户 履 盖 默 认 的 Hibernate 类 型 到 SQL 数据 类 型 的 映射 。 


<property name="balance" type="float"> 
<column name="balance" sql-type="decimal(13,3)"/> 
</property> 


check 属性 允许 用 户 指 定 一 个 约束 检查 。 


<property name="foo" type="integer"> 
<column name="foo" check="foo > 10"/> 
</property> 


<class name="Foo" table="foos" check="bar < 100.0"> 


<property name="bar" type="float"/> 
</class> 


表 20.1. Summary 


属性 (Attribute) 值 (Values ) 解释 (Interpretatior 


length 数字 字段 长 度 

precision 数字 精度 (decimal precision) 

scale 数字 小 数 点 位 数 (decimal scale) 
not-null true&#124; false 指明 字段 是 否 应 该 是 非 空 的 

unique true&#124; false 章 明 是 否 该 字段 具有 惟一 约束 
index index_name 指明 一 个 (多 字段 ) 的 索引 (index) 的 
unique-key unique_key_name 指明 多 字段 惟一 约束 的 名 字 (参见 上 


specifies the name of the foreign key 
generated for an association, for a 
&lt;one-to-one&gt; , &lt;many 
&lt;key&gt; ,or &lt;many-to-m 
mapping element. Note that invers 
foreign-key foreign_key_name will not be considered by SchemaEx 
外 键 的 名 字 ， 它 是 为 关联 生成 的 ， 或 
者 &lt;one-to-one&gt; ， &lt;mé 
&lt;key&gt; ,或 者 &lt;many-to- 
元 素 。 注 意 inverse="true" 在 Sc 


被 忽略 。 
ASTE SQL 字段 类 型 gt 能 用 于 elt; 
default SQL 表达 式 为 字段 指定 默认 值 
check SQL 表达 式 对 字段 或 表 加 入 SQL 约束 检查 


&lt;comment&gt; 元 素 可 以 让 你 在 生成 的 Schema 中 加 入 注释 。 


<class name="Customer" table="CurCust"> 
<comment>Current customers only</comment> 


</class> 


<property name="balance"> 
<column name="bal"> 
<comment>Balance in USD</comment> 
</column> 
</property> 


结果 是 在 生成 的 DDL 中 包含 comment on table 或 者 comment on column 7% 4) 
(假若 支持 的 话 )。 


20.1.2. 运行 芒 工 具 
SchemaExport 工具 把 DDL 脚 本 写 到 标准 输出 ， 同 时 /或 者 执行 DDL 语 句 。 


java -cp hibernate_classpaths 
org.hibernate.tool.hbm2dd1.SchemaExport options mapping_files 


表 20.2. SchemaExport 命令 行 选项 


选项 说 明 
--quiet 不 要 把 脚本 输出 到 stdout 
--drop 只 进行 drop tables 的 步骤 
--create 只 创建 表 
extE 不 执行 在 数据 库 中 运行 的 步骤 
- -output=my_schema. dd1 把 输出 的 ddl 脚 本 输出 到 一 个 文件 


- -naming=eg.MyNamingStrategy ee 
--config=hibernate.cfg.xml 从 XML 文件 读 入 Hibernate 配 置 
--properties=hibernate.properties 从 文件 读 入 数据 库 属 性 
--format 把 脚本 中 的 SQL 语句 对 齐 和 美化 


=-de limiter=- 为 脚本 设置 行 结束 符 


你 甚至 可 以 在 你 的 应 用 程序 中 黎 入 SchemaExport LH: 


Configuration cfg = ... 
new SchemaExport(cfg). create(false, true); 


20.1.3. 属性 (Properties) 


可 以 通过 如 下 方式 指定 数据 库 属 性 : 

e 通过 -D <property> 系 统 参 数 

e 在 hibernate.properties 文件 中 

e 位 于 一 个 其 它 名 字 的 properties 文 件 中 ,然后 用 --properties 参数 指定 
所 需 的 参数 包括 : 


表 20.3. SchemaExport 连接 属性 


属性 名 说 明 
hibernate.connection.driver_class jdbc driver class 
hibernate.connection.url jdbc url 
hibernate.connection. username database user 
hibernate.connection.password user password 


hibernate.dialect 7 @ (dialect) 


20.1.4. 使 用 Ant(Using Ant) 
你 可 以 在 你 的 Ant build 脚 本 中 调用 SchemaExport : 


<target name="Schemaexport"> 
<taskdef name="schemaexport" 
classname="org.hibernate.tool.hbm2dd1.SchemaExportTask" 
classpathref="class.path"/> 


<schemaexport 
properties="hibernate.properties" 
quiet="no" 
text="no" 
drop="no" 
delimiter=";" 
output="schema-export.sql"> 
<fileset dir="src"> 

<include name="**/*.hom.xm1l"/> 

</fileset> 

</schemaexport> 

</target> 


20.1.5. 对 Schema 的 增 量 更 新 (Incremental 
schema updates) 
SchemaUpdate 工具 对 已 存在 的 Schema 采用 " 增 量 "方式 进行 更 新 。 注 


意 SchemaUpdate 严重 依赖 于 JDBC metadata API, 所 以 它 并 非 对 所 有 JDBC 驱 动 都 
有 效 。 


java -cp hibernate_classpaths 
org.hibernate.tool.hbm2dd1.SchemaUpdate options mapping_files 


# 20.4. SchemaUpdate 命令 行 选项 


选项 说 明 
--quiet 不 要 把 脚本 输出 到 stdout 
St 不 把 脚本 输出 到 数据 库 
选择 一 个 命名 策略 


--naming=eg.MyNamingStrategy (WD 


--properties=hibernate.properties 从 指定 文件 读 入 数据 库 属 性 


--config=hibernate.cfg.xml 间 定 一 个 ,cfg.xml 文件 
UR Py VA FER A oF EJ PRA SchemaUpdate 工具 : 


Configuration cfg = .. 
new SchemaUpdate(cfg). ee TT 


20.1.6. 用 Ant 来 增 量 更 新 Schema(Using Ant for 
incremental schema updates) 


你 可 以 在 Ant 脚 本 中 调用 SchemaUpdate 


<target name="Schemaupdate"> 
<taskdef name="schemaupdate" 
classname="org.hibernate.tool.hbm2dd1.SchemaUpdateTask" 
classpathref="class.path"/> 


<schemaupdate 
properties="hibernate.properties" 
quiet="no"> 
<fileset dir="src"> 

<include name="**/*.hbom.xm1l"/> 

</fileset> 

</schemaupdate> 

</target> 


20.1.7. Schema 校 验 


SchemaValidator 工具 会 比较 数据 库 现 状 是 否 与 映射 文档 “匹配 ”。 注 


意 ， SchemaValidator 严重 依赖 于 JDBC 的 metadata API， 因 此 不 是 对 所 有 的 
JDBC 驱 动 都 适用 。 这 一 工具 在 测试 的 时 候 特别 有 用 。 


java -cp hibernate_classpaths 
org.hibernate.tool.hbm2dd1.SchemaValidator options mapping_files 


# 20.5. SchemaValidator 命令 行 参 数 


选项 描述 
一 个 命 
- -naming=eg.MyNamingStrategy 选择 全 名 策略 


( NamingStrategy ) 
--properties=hibernate.properties 从 文件 中 读 取 数据 库 届 性 
--config=hibernate.cfg.xml 指定 一 个 ,cfg,xml 文件 


你 可 以 在 你 的 应 用 程序 中 岁入 Schemavalidator 


Configuration cfg = ....; 
new SchemaValidator (cfg). ‘validate(); 


20.1.8. 使 用 Ant 进 行 sSchema 校 验 
你 可 以 在 Ant 脚 本 中 调用 Schemavalidator : 


<target name="Schemavalidate"> 
<taskdef name="schemavalidator" 
classname="org.hibernate.tool.hbm2dd1.SchemaValidatorTas 
k" 
classpathref="class.path"/> 


<schemavalidator 
properties="hibernate.properties"> 
<fileset dir="src"> 
<include name="**/*.hbm.xml"/> 
</fileset> 
</schemaupdate> 
</target> 


第 21 章 示例 : 父子 关系 (Parent Child 
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刚刚 接触 Hibernate 的 人 大 多 是 从 父子 关系 (parent / child type relationship) 的 建 
模 入 手 的 。 父 子 关系 的 建 模 有 两 种 方法 。 由 于 种 种 原因 ， 最 方便 的 方法 是 

把 Parent 和 Child 都 建 模 成 实体 类 ， 并 创建 一 个 从 Parent 指向 Child 的 
<one-to-many> 关 联 ， 对 新 手 来 说 尤其 如 此 。 还 有 一 种 方法 ， 就 是 将 Child 声明 
为 一 个 &lt;composite-elementagt; (组 合 元 素 ) 。 事实 上 在 Hibernate 中 one 
to many 关 联 的 默认 语义 远 没 有 composite element 贴 近 parent / child 关 系 的 通常 语 
义 。 下 面 我 们 会 阔 述 如 何 使 用 带 有 级 联 的 双向 一 对 多 关联 (bidirectional one to 
many association with cascaaes) 去 建立 有 效 、 优 美的 parent / child 关 系 。 这 一 点 也 
不 难 |! 


21.1. 关于 collections 需 要 注意 的 一 点 


重要 ! 它 主要 体现 为 以 下 几 点 : 
o 当 删 除 或 增加 collection 中 对 象 的 时 候 ，collection 所 属 者 的 版 本 值 会 递增 。 


e@ 如 果 一 个 从 collection 中 移 除 的 对 象 是 一 个 值 类 型 (value type) 的 实例 ， 比 如 
composite element， 那 么 这 个 对 象 的 持久 化 状态 将 会 终止 ， 其 在 数据 库 中 对 应 
的 记录 会 被 删除 。 同 样 的 ， 向 collection 增 加 一 个 value type 的 实例 将 会 使 之 立 
即 被 持久 化 。 


© 另 一 方面 ， 如 果 从 一 对 多 或 多 对 多 关联 的 collection 中 移 除 一 个 实体 ， 在 缺 省 情 
况 下 这 个 对 象 并 不 会 被 删除 。 这 个 行为 是 完全 合 手 逻辑 的 一 一 改变 一 个 实体 的 
内 部 状态 不 应 该 使 与 它 关 联 的 实体 消失 掉 ! 同样 的 ， 向 collection 增 加 一 个 实体 
不 会 使 之 被 持久 化 。 


实际 上 ， 向 Collection 增 加 一 个 实体 的 缺 省 动作 只 是 在 两 个 实体 之 间 创 建 一 个 连接 而 
已 ， 同 样 移 除 的 时 候 也 只 是 删除 连接 。 这 种 处 理 对 于 所 有 的 情况 都 是 合适 的 。 对 于 
父子 关系 则 是 完全 不 适合 的 ， 在 这 种 关系 下 ， 子 对 象 的 生存 绑 定 于 父 对 象 的 生存 周 
期 。 


21.2. 双向 的 一 对 多 关系 (Bidirectional one-to- 
many) 


假设 我 们 要 实现 一 个 简单 的 从 Parent 到 Child 的 <one-to-many> 关 联 。 


<set name="children"> 
<key column="parent_id"/> 
<one-to-many class="Child"/> 
</set> 


果 我 们 运行 下 面 的 代码 


Parent p= ..... 
Child c = new O 
p. ec re add(c); 
session.save(c); 
session.flush(); 


Hibernate 4 * 4 A ASQLi& 4 : 

e 一 条 INSERT 724° A c 创建 一 条 记录 

e 一 条 UPDATE 4° CI2M p 到 c 的 连接 
这 样 做 不 仅 效 率 低 ， 而 且 违 反 了 列 parent_id 非 空 的 限制 。 我 们 可 以 通过 在 集合 
类 映射 上 指定 not-null="true" 来 解决 违反 非 空 约束 的 问题 : 


<set name="children"> 
<key column="parent_id" not-null="true"/> 
<one-to-many class="Child"/> 

</set> 


然而 ， 这 并 非 是 推荐 的 解决 方法 。 
这 种 现象 的 根本 原因 是 从 p 到 c 的 连接 (外 键 parent id) 没有 被 当 作 child 对 


象 状态 的 一 部 分 ， 因 而 没有 在 INSERT 语 句 中 被 创建 。 因 此 解决 的 办 法 就 是 把 这 个 
连接 添加 到 Child 的 映射 中 。 


<many-to-one name="parent" column="parent_id" not-null="true"/> 


(我 们 还 需要 为 类 Child 添加 parent 属性 ) 


现在 实体 Child 在 管理 连接 的 状态 ， 为 了 使 collection 不 更 新 连接 ， 我 们 使 
用 inverse 属性 。 


<set name="Children" inverse="true"> 
<key column="parent_id"/> 
<one-to-many class="Child"/> 
</set> 


下 面 的 代码 是 用 来 添加 一 个 新 的 Child 


Parent p = (Parent) session.load(Parent.class, pid); 
Child c = new Child(); 

c.setParent(p); 

p.getChildren().add(c); 

session.save(c); 

session.flush(); 


现在 ， 只 会 有 一 条 INSERT 语句 被 执行 ! 


为 了 让 事情 变 得 并 并 有 条 ， 可 以 为 Parent 加 一 个 addChild() 方法 。 


public void addChild(Child c) { 
c.setParent(this); 
children.add(c); 


现在 ， 添 加 Child 的 代码 就 是 这 样 


Parent p = (Parent) session.load(Parent.class, pid); 
Child c = new Child(); 

p.addChild(c); 

session.save(Cc); 

session. flush(); 


21.3. 级 联 生 全 周期 (Cascading lifecycle ) 
需要 显 式 调用 save() 仍然 很 麻烦 ， 我 们 可 以 用 级 联 来 解决 这 个 问题 。 


<set name="children" inverse="true" cascade="all"> 
<key column="parent_id"/> 
<one-to-many class="Child"/> 

</set> 


这 样 上 面 的 代码 可 以 简化 为 : 


Parent p = (Parent) session.load(Parent.class, pid); 
Child c = new Child(); 

p.addChild(c); 

session.flush(); 


同样 的 ， 保 存 或 删除 Parent 对 象 的 时 候 并 不 需要 遍历 其 子 对 象 。 下 面 的 代码 会 
删除 对 象 p 及 其 所 有 子 对 象 对 应 的 数据 库 记 录 。 


Parent p = (Parent) session.load(Parent.class, pid); 
session.delete(p); 
session.flush(); 


然而 ， 这 上 段 代码 


Parent p = (Parent) session.load(Parent.class, pid); 
Child c = (Child) p.getChildren().iterator().next(); 
p.getChildren().remove(c); 

c.setParent(null); 

session. flush(); 


不 会 从 数据 库 删 除 c ; ER 
B NOT NULL 约束 ， 在 这 人 1 
除 Child 。 


会 删除 与 p 之 间 的 连接 (并 且 会 导致 违 
例子 中 ) 。 你 需要 显 式 调用 delete() XM 


Parent p = (Parent) session.load(Parent.class, pid); 
Child c = (Child) p.getChildren().iterator().next(); 
p.getChildren().remove(c); 

session.delete(c); 

session.flush(); 


在 我 们 的 例子 中 ， 如 果 没 有 父 对 银 ， Le 
collection 中 移 除 ， 实 际 上 我 们 是 想 删除 它 。 要 实现 这 种 要 求 ， 就 必须 使 
用 cascade="all-delete-orphan" 。 


<Set name="Children" inverse="true" cascade="all-delete-orphan"> 
<key column="parent_id"/> 
<one-to-many class="Child"/> 

</set> 


注意 : 即使 在 collection 一 方 的 映射 中 指定 inverse="true" ， 级 联 仍然 是 通过 遍 
历 collection 中 的 元 素来 处 理 的 。 如 果 你 想 要 通过 级 联 进行 子 对 象 的 插入 、 删 除 、 更 
新 操作 ， 就 必须 把 它 加 到 collection 中 ， 只 调用 setParent() 是 不 够 的 。 


21.4. 级 联 与 未 保存 值 (Cascades and 
unsaved-value ) 


假设 我 们 从 Session PRAT —* Parent 对 象 ， 用 户 界 面 对 其 进行 了 修改 ， 然 
后 希望 在 一 个 新 的 Session 里 面 调 用 update() 来 保存 这 些 修 改 。 对 象 Parent & 
含 了 子 对 象 的 集合 ， 由 于 打开 了 级 联 更 新 ，Hibernate 需 要 知道 哪些 Child 对 象 是 新 
实例 化 的 ， 哪 些 代表 数据 库 中 已 经 存在 的 记录 。 我 们 假设 Parent 和 Child 对 象 
的 标识 属性 都 是 自动 生成 的 ， 类 型 为 java.lang.Long 。Hibernate 会 使 用 标识 
性 的 值 ， 和 version 或 timestamp 属性 ， 来 判断 哪些 子 对 象 是 新 的 。( 参 见 第 10.7 
节 “ 自 动 状态 检测 ”.) 在 Hibernate3 中 , 显 式 指定 unsaved-value 不 再 是 必须 的 


下 面 的 代码 会 更 新 parent 和 child 对 象 ， 并 且 插 入 newChild 对 象 。 


//parent and child were both loaded in a previous session 
parent.addChild(child); 

Child newChild = new Child(); 

parent.addChild(newChild) ; 

session.update(parent); 

session.flush(); 


Well, that's all very well for the case of a generated identifier, but what about 
assigned identifiers and composite identifiers? This is more difficult, since 
Hibernate can't use the identifier property to distinguish between a newly 
instantiated object (with an identifier assigned by the user) and an object loaded in 
a previous session. In this case, Hibernate will either use the timestamp or version 
property, or will actually query the second-level cache or, worst case, the 
database, to see if the row exists. 


这 对 于 自动 生成 标识 的 情况 是 非常 好 的 ， 但 是 自分 配 的 标识 和 复合 标识 怎么 办 呢 ? 
这 是 有 点 麻烦 ， 因 为 Hibernate 没 有 办 法 区 分 新 实例 化 的 对 象 (标识 被 用 户 指定 了 ) 
和 前 一 个 Session 装 入 的 对 象 。 在 这 种 情况 下 ，Hibernate 会 使 用 timestamp 或 
version 属 性 ， 或 者 查询 第 二 级 缓存 ， 或 者 最 坏 的 情况 ， 查 询 数 据 库 ， 来 确认 是 否 此 
行 存在 。 


21.5. 结论 


这 里 有 不 少 东 西 需要 融会 贯通 ， 可 能 会 让 新 手感 到 迷惑 。 但 是 在 实践 中 它们 都 工作 
地 非常 好 。 大 部 分 Hibernate 应 用 程序 都 会 经 常用 到 父子 对 象 模式 。 


在 第 一 段 中 我 们 曾经 提 到 另 一 个 方案 。 上 面 的 这 些 问题 都 不 会 出 现 
在 &lt;composite-element&gt; 映射 中 ， 它 准确 地 表达 了 父子 关系 的 语义 。 很 
不 幸 复 合 元 素 还 有 两 个 重大 限制 :复合 元 素 不 能 拥有 collections， 并 且 ， 除 了 用 于 惟 
一 的 父 对 象 外 ， 它 们 不 能 再 作为 其 它 任何 实体 的 子 对 象 。 


第 22 章 示例 : Weblog 应 用 程序 


目录 


e 22.1. 持久 化 类 
e 22.2. Hibernate 映射 
e 22.3. Hibernate 代码 


22.1. 持久 化 类 


下 面 的 持久 化 类 表示 一 个 weblog 和 在 其 中 张贴 的 一 个 贴 子 。 他 们 是 标准 的 父 / 子 关 
系 模型 ， 但 是 我 们 会 用 一 个 有 序 包 (ordered bag) 而 非 集合 (set)。 


package eg; 

import java.util.List; 

public class Blog { 
private Long _id; 
private String _name; 


private List _items; 


public Long getId() { 
return _id; 


public List getItems() { 
return _items; 


} 
public String getName() { 
return _name; 


public void setId(Long long1) { 
_id = longi; 


public void setItems(List list) { 
_items = list; 


public void setName(String string) { 
_name = string; 
} 


package eg; 


import java.text.DateFormat; 
import java.util.Calendar; 


public class BlogItem { 
private Long _id; 
private Calendar _datetime; 
private String _text; 
private String _title; 
private Blog _blog; 


public Blog getBlog() { 
return _blog; 


public Calendar getDatetime() { 
return _datetime; 


} 
public Long getId() { 


return _id; 
} 


public String getText() { 
return _text,; 


public String getTitle() { 
return _title; 


} 
public void setBlog(Blog blog) { 
_blog = blog; 


public void setDatetime(Calendar calendar) { 
_datetime = calendar; 


public void setId(Long long1) { 
_id = longi; 


public void setText(String string) { 
_text = string; 


public void setTitle(String string) { 
_title = string; 


} 


22.2. Hibernate 映射 
下 列 的 XML 映射 应 该 是 很 直 白 的 。 


<?xml version="1.0"?> 
<!DOCTYPE hibernate-mapping PUBLIC 
"-//Hibernate/Hibernate Mapping DTD 3.0//EN" 
"http://hibernate.sourceforge.net/hibernate-mapping-3.0. 
dtd"> 


<hibernate-mapping package="eg"> 
<class 
name="Blog" 
table="BLOGS" > 


<id 
name="id" 
column="BLOG_ID"> 


<generator class="native"/> 
</id> 


<property 
name="name" 
column="NAME" 
not-null="true" 
unique="true"/> 


<bag 
name="items" 
inverse="true" 
order -by="DATE_TIME" 
cascade="all"> 


<key column="BLOG_ID"/> 
<one-to-many class="BlogItem"/> 


</bag> 
</class> 


</hibernate-mapping> 


<?xml version="1.0"?> 
<!DOCTYPE hibernate-mapping PUBLIC 
"-//Hibernate/Hibernate Mapping DTD 3.0//EN" 
"http://hibernate.sourceforge.net/hibernate-mapping-3.0. 
dtd"> 


<hibernate-mapping package="eg"> 


<class 
name="BlogItem" 
table="BLOG_ITEMS" 
dynamic -update="true"> 


<id 
name="id" 
column="BLOG_ITEM_ID"> 


<generator class="native"/> 
</id> 


<property 
name="title" 
column="TITLE" 
not-null="true"/> 


<property 
name="text" 
column="TEXT" 
not-null="true"/> 


<property 
name="datetime" 
column="DATE_TIME" 
not-null="true"/> 


<many-to-one 
name="blog" 
column="BLOG_ID" 
not-null="true"/> 
</class> 


</hibernate-mapping> 


22.3. Hibernate 代码 


下 面 的 类 演示 了 我 们 可 以 使 用 Hibernate 对 这 些 类 进 


D 
& 
pa 
Ji 
`~ 
a 
O 


package eg; 


import java.util.ArrayList; 
import java.util.Calendar; 
import java.util.Iterator; 
import java.util.List; 


import org.hibernate.HibernateException; 

import org.hibernate.Query; 

import org.hibernate.Session; 

import org.hibernate.SessionFactory; 

import org.hibernate.Transaction; 

import org.hibernate.cfg.Configuration; 

import org.hibernate.tool.hbm2dd1.SchemaExport; 


public class BlogMain { 


private SessionFactory _sessions; 


public void configure() throws HibernateException { 
_sessions = new Configuration() 
.addClass(Blog.class) 
.addClass(BlogItem.class) 
.buildSessionFactory(); 


} 


public void exportTables() throws HibernateException { 
Configuration cfg = new Configuration() 
.addClass(Blog.class) 
.addClass(BlogItem.class); 
new SchemaExport(cfg).create(true, true); 


} 


public Blog createBlog(String name) throws HibernateExceptio 


Blog blog = new Blog(); 
blog.setName(name) ; 
blog.setItems( new ArrayList() ); 


Session session = _sessions.openSession(); 
Transaction tx = null; 
try { 


tx = session.beginTransaction(); 
session.persist(blog); 


tx.commit(); 


} 


catch (HibernateException he) { 
if (tx!=null) tx.rollback(); 


throw he; 
} 
finally { 
session.close(); 
} 


return blog; 


} 


public BlogItem createBlogItem(Blog blog, String title, Stri 
ng text) 
throws HibernateException { 


BlogItem item = new BlogItem(); 
item.setTitle(title); 

item.setText(text); 

item.setBlog(blog); 

item.setDatetime( Calendar.getInstance() ); 
blog.getItems().add(item); 


Session session = _sessions.openSession(); 
Transaction tx = null; 
try { 


tx = session.beginTransaction(); 
session.update(blog); 
tx.commit(); 


catch (HibernateException he) { 
if (tx!=null) tx.rollback(); 


throw he; 
} 
finally { 
session.close(); 
} 


return item; 


} 


public BlogItem createBlogItem(Long blogid, String title, St 
ring text) 
throws HibernateException { 


BlogItem item = new BlogItem(); 
item.setTitle(title); 

item.setText(text); 

item.setDatetime( Calendar.getInstance() ); 


Session session = _sessions.openSession(); 
Transaction tx = null; 
try { 


tx = session.beginTransaction(); 


Blog blog = (Blog) session.load(Blog.class, blogid); 


item.setBlog(blog); 
blog.getItems().add(item) ; 
tx.commit(); 


catch (HibernateException he) { 
if (tx!=null) tx.rollback(); 


throw he; 
} 
finally { 
session.close(); 
} 


return item; 


} 


public void updateBlogItem(BlogItem item, String text) 
throws HibernateException { 


item.setText(text); 


Session session = _sessions.openSession(); 
Transaction tx = null; 
try { 


tx = session.beginTransaction(); 
session.update(item) ; 
tx.commit(); 


catch (HibernateException he) { 
if (tx!=null) tx.rollback(); 


throw he; 
} 
finally { 
session.close(); 
} 


} 


public void updateBlogItem(Long itemid, String text) 
throws HibernateException { 


Session session = _sessions.openSession(); 
Transaction tx = null; 
try { 


tx = session.beginTransaction(); 


BlogItem item = (BlogItem) session.load(BlogItem. 


ss, itemid); 
item.setText(text); 
tx.commit(); 


catch (HibernateException he) { 
if (tx!=null) tx.rollback(); 
throw he; 


} 
finally { 


cla 


session.close(); 


} 


public List listAllBlogNamesAndItemCounts(int max) 
throws HibernateException { 


Session session = _sessions.openSession(); 
Transaction tx = null; 
List result = null; 
try { 
tx = session.beginTransaction(); 
Query q = session.createQuery( 
"select blog.id, blog.name, count(blogItem) " + 
"from Blog as blog " + 
"left outer join blog.items as blogItem " + 
"group by blog.name, blog.id " + 
"order by max(blogiItem.datetime)" 
); 
q.setMaxResults(max); 
result = q.list(); 
tx.commit(); 


catch (HibernateException he) { 
if (tx!=null) tx.rollback(); 


throw he; 
} 
finally { 
session.close(); 
} 


return result; 


} 


public Blog getBlogAndAllItems(Long blogid) 
throws HibernateException { 


Session session = _sessions.openSession(); 
Transaction tx = null; 
Blog blog = null; 
try { 
tx = session.beginTransaction(); 
Query q = session.createQuery( 
"from Blog as blog " + 
"left outer join fetch blog.items " + 
"where blog.id = :blogid" 
); 
q.setParameter("blogid", blogid); 
blog = (Blog) q.uniqueResult(); 
tx.commit(); 


catch (HibernateException he) { 
if (tx!=null) tx.rollback(); 
throw he; 


} 
finally { 


session.close(); 


} 


return blog; 


} 


public List listBlogsAndRecentItems() throws HibernateExcept 
ion { 


Session session = _sessions.openSession(); 
Transaction tx = null; 
List result = null; 
try { 
tx = session.beginTransaction(); 
Query q = session.createQuery( 
"from Blog as blog " + 
"inner join blog.items as blogItem " + 
"where blogItem.datetime > :minDate" 


); 


Calendar cal = Calendar.getInstance(); 
cal.roll(Calendar.MONTH, false); 
q.setCalendar("minDate", cal); 


result = q.list(); 
tx.commit(); 


catch (HibernateException he) { 
if (tx!=null) tx.rollback(); 


throw he; 
} 
finally { 
session.close(); 
} 


return result; 


第 23 È 示例 : 复杂 映射 实例 


目录 
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o 23.4.2. Composite key example 
o 23.4.3. 共有 组 合 键 属性 的 多 对 多 (Many-to-many with shared composite 
key attribute ) 
o 23.4.4. Content based discrimination 
o 23.4.5. Associations on alternate keys 


本 章 展 示 了 一 些 较 为 复杂 的 关系 映射 。 


23.1. Employer (Æ +)/Employee(# it) 


下 面 关 于 Employer 和 Employee 的 关系 模型 使 用 了 一 个 真实 的 实体 类 
( Employment ) 来 表述 ， 这 是 因为 对 于 相同 的 雇员 和 雇主 可 能 会 有 多 个 雇佣 时 间 
段 。 对 于 金额 和 雇员 姓名 ， 用 Components 建 模 。 













Employment 
-startDate : Date 
-endDate : Date 







Employee 






















hes 





-id : long 
-taxfileNumber : String 


-firstName : String 
name] -initial : char 





+employee 



























-id : long +getNamed : Name -lastName : String 
+setldLid:long) +getStartDated : Date +setName(name:Name) +getFirstNamed : String 
+getNamed : String +setStartDate(startDate:Date) +getidd : long +setFirstName(_firstName String) 
+setName(_namesString) +qgetEndDated : Date +setidLid:long) +getinitiald : char 


+setEndDateLendDate:Date) 
+getHourlyRated : MonetoryAmount 
+setHourlyRatetrate:MonetoryAmount) 
+getldd : long 
+setidLid:long) 
+getEmployerd : Employer 
+setEmployertemp:Employen 
+getEmployeed : Employee 
+setEmployeelemp:Employee) 


+getTaxfileNumberd : String 
+setTaxfileNumber(taxfileNumbersString) 


+setinitialCinitial:chan 
+getLastNamed : String 
+setLastName(lastName:String) 














+hourlyRat MonetoryAmount 
-amount : BigDecimal 





-currency : Currency 








+getAmountd : BigDecimal 


+setAmountL_amount:BigDecimal 
+qgetCurrencyd : Currency 
+setCurrencycurrency:Currency) 





映射 文件 可 能 是 这 样 : 


<hibernate-mapping> 


<class name="Employer" table="employers"> 
<id name="id"> 
<generator class="Ssequence"> 
<param name="Ssequence">employer_id_seq</param> 
</generator> 
</id> 
<property name="name"/> 
</class> 


<class name="Employment" table="employment_periods"> 


<id name="id"> 
<generator class="sequence"> 
<param name="sSequence">employment_id_seq</param> 
</generator> 
</id> 
<property name="StartDate" column="start_date"/> 
<property name="endDate" column="end_date"/> 


<component name="hourlyRate" class="MonetaryAmount"> 
<property name="amount"> 
<column name="hourly_rate" sql-type="NUMERIC(12, 
2)"/> 
</property> 
<property name="Currency" length="12"/> 
</component> 


<many-to-one name="employer" column="employer_id" not-nu 
11="true"/> 

<many-to-one name="employee" column="employee_id" not-nu 
11="true"/> 


</class> 


<class name="Employee" table="employees"> 
<id name="id"> 
<generator class="sequence"> 
<param name="sSequence">employee_id_seq</param> 
</generator> 
</id> 
<property name="taxfileNumber"/> 
<component name="name" class="Name"> 
<property name="firstName"/> 
<property name="initial"/> 
<property name="lastName"/> 
</component> 
</class> 


</hibernate-mapping> 


用 SchemaExport 生成 表 结 构 。 


create table employers ( 
id BIGINT not null, 
name VARCHAR(255), 
primary key (id) 

) 


create table employment_periods ( 
id BIGINT not null, 
hourly_rate NUMERIC(12, 2), 
currency VARCHAR(12), 
employee_id BIGINT not null, 
employer_id BIGINT not null, 
end_date TIMESTAMP, 
start_date TIMESTAMP, 
primary key (id) 

) 


create table employees ( 
id BIGINT not null, 
firstName VARCHAR(255), 
initial CHAR(1), 
lastName VARCHAR( 255), 
taxfileNumber VARCHAR( 255), 
primary key (id) 

) 


alter table employment_periods 
add constraint employment_periodsFKO foreign key (employer_i 
d) references employers 
alter table employment_periods 
add constraint employment_periodsFK1i foreign key (employee_i 
d) references employees 
create sequence employee_id_seq 
create sequence employment_id_seq 
create sequence employer_id_seq 


23.2. Author( 作 家 )/Work( 作 品 ) 


考虑 下 面 的 Work , Author 和 Person 模型 的 关系 。 我 们 用 多 对 多 关系 来 描 
zt Work 和 Author ， 用 一 对 一 关系 来 描述 Author 和 Person > 5—4 T 
能 性 是 Author 继承 Person 。 



















-id : long -id : long -id : long 
-title : String ” | -alias : String -name : String 


+getldd : long q+getidd : long 十 getldn : long 
+setldLid:long) +setldLid:long) +setldLid:long) 
+qgetAuthorsd : Set 十 getWorksn0 : Set +getNamed : String 
+setAuthorslemployees:Set) +setwWorkstemployers:Set) +setNametname:String) 
+getTitled : String +getPersond : Person 
+setTitletitle:String) +setPersoniperson:Persom 

+qgetAliasd : String 

+setAliasalias:String) 










Book 


| Song [tok | 


-tempo : float 
+getGenred : String 
+setGenre(genre String) 


+getTempood : float 
+setTempottempo:float) 


+getTextd : int 
+setTextLtext:int) 


下 面 的 映射 文件 正确 的 描述 了 这 些 关系 : 


<hibernate-mapping> 
<class name="Work" table="works" discriminator -value="W"> 


<id name="id" column="id"> 
<generator class="native"/> 
</id> 
<discriminator column="type" type="character"/> 


<property name="title"/> 
<set name="authors" table="author_work"> 
<key column name="work_id"/> 
<many-to-many class="Author" column name="author_id" 
/> 
</set> 


<subclass name="Book" discriminator -value="B"> 
<property name="text"/> 
</subclass> 


<subclass name="Song" discriminator -value="S"> 
<property name="tempo"/> 


<property name="genre"/> 
</subclass> 


</class> 
<class name="Author" table="authors"> 


<id name="id" column="id"> 
<!-- The Author must have the same identifier as the 


Person --> 
<generator class="assigned"/> 


</id> 


<property name="alias"/> 
<one-to-one name="person" constrained="true"/> 


<set name="works" table="author_work" inverse="true"> 
<key column="author_id"/> 
<many-to-many class="Work" column="work_id"/> 


</set> 
</class> 


<class name="Person" table="persons"> 
<id name="id" column="id"> 
<generator class="native"/> 
</id> 
<property name="name"/> 
</class> 


</hibernate-mapping> 
映射 中 有 4 个 表 。 works , authors 和 persons 分 别 保 存 着 work，author 和 


person 的 数据 。 author_work 是 authors 和 works 的 关联 表 。 表 结 构 是 
由 SchemaExport 生成 的 。 


create table works ( 
id BIGINT not null generated by default as identity, 
tempo FLOAT, 
genre VARCHAR(255), 
text INTEGER, 
title VARCHAR(255), 
type CHAR(1) not null, 
primary key (id) 
) 


create table author_work ( 
author_id BIGINT not null, 
work_id BIGINT not null, 
primary key (work_id, author_id) 


) 


create table authors ( 
id BIGINT not null generated by default as identity, 
alias VARCHAR(255), 
primary key (id) 

) 


create table persons ( 
id BIGINT not null generated by default as identity, 
name VARCHAR( 255), 
primary key (id) 

) 


alter table authors 

add constraint authorsFKO foreign key (id) references person 
S 
alter table author_work 

add constraint author_workFKO foreign key (author_id) refere 
nces authors 
alter table author_work 

add constraint author_workFK1 foreign key (work_id) referenc 
es works 


23.3. Customer( 客 户 )/Order( 订 单 )/Product( 产 品 ) 


现在 来 考虑 Customer , Order ， LineItem 和 Product 关系 的 模 

型 。 Customer 和 Order 之 间 是 一 对 多 的 关系 ， 但 是 我 们 怎么 来 描述 Order / 
LineItem / Product 呢 ? 我 可 以 把 LineItem 作为 描述 Order 和 

Product 多 对 多 关系 的 关联 类 ， 丰 Hibernate， 这 叫做 组 合 元 素 。 


Customer 
-id : long 
-name : String 
+getldù : long 
+setldLid:long) 
+getNamed : String 
+setNamelname:String) 
+getOrdersd : Set 
+setOrderslorders:Set) 








映射 文件 如 下 : 




















+customer +orders 





















Order Lineltem Product 
党 -id : long -id : long 
-date : Date -5erialNumber : String 
+getldd : long +setQuantity(quantity:int) +getldd : long 
+setldLid:long) +qgetProductd : Product +setldLid:long) 


+getSerialNumberd : String 
+setSerialNumber(_serialNumberString) 


+getLineltemsd : List +setProductiproduct:Product) 
+setLineltemstlineltems:List) 
+getCustomerd : Customer 
+setCustomer(customer:Customen 
+getDated : Date 


+setDate(_date:Date) 





<hibernate-mapping> 


<class name="Customer" table="Ccustomers"> 
<id name="id"> 
<generator class="native"/> 
</id> 
<property name="name"/> 
<set name="orders" inverse="true"> 
<key column="customer_id"/> 
<one-to-many class="Order"/> 
</set> 
</class> 


<class name="Order" table="orders"> 
<id name="id"> 
<generator class="native"/> 
</id> 
<property name="date"/> 
<many-to-one name="Customer" column="Ccustomer_id"/> 
<list name="lineItems" table="line_items"> 
<key column="order_id"/> 
<list-index column="line_number"/> 
<composite-element class="LineItem"> 
<property name="quantity"/> 
<many-to-one name="product" column="product_id"/ 


</composite-element> 
</list> 
</class> 


<class name="Product" table="products"> 
<id name="id"> 
<generator class="native"/> 
</id> 
<property name="SserialNumber"/> 
</class> 


</hibernate-mapping> 
customers , orders , line_items 和 products 分 别 保存 着 customer, 


order, order line item 和 product 的 数据 。 line_items 也 作为 连接 orders 和 
products 的 关联 表 。 


create table customers ( 
id BIGINT not null generated by default as identity, 
name VARCHAR( 255), 
primary key (id) 

) 


create table orders ( 
id BIGINT not null generated by default as identity, 
customer_id BIGINT, 
date TIMESTAMP, 
primary key (id) 
) 


create table line_items ( 
line_number INTEGER not null, 
order_id BIGINT not null, 
product_id BIGINT, 
quantity INTEGER, 
primary key (order_id, 1line_number ) 


) 


create table products ( 
id BIGINT not null generated by default as identity, 
serialNumber VARCHAR(255), 
primary key (id) 

) 


alter table orders 

add constraint ordersFKO foreign key (customer_id) reference 
s customers 
alter table line_items 

add constraint line_itemsFKO foreign key (product_id) refere 
nces products 
alter table line_items 

add constraint line_itemsFK1i foreign key (order_id) referenc 
es orders 


23.4. #4! 


这 些 例子 全 部 来 自 于 Hibernate 的 test suite， 同 时 你 也 可 以 找到 其 他 有 用 的 例子 。 
可 以 参考 Hibernate 的 test 目录 。 


TODO: put words around this stuff 


23.4.1. "Typed" one-to-one association 


<class name="Person"> 
<id name="name"/> 
<one-to-one name="address" 
cascade="all"> 
<formula>name</formula> 
<formula>'HOME'</formula> 
</one-to-one> 
<one-to-one name="mailingAddress" 
cascade="all"> 
<formula>name</formula> 
<formula>'MAILING'</formula> 
</one-to-one> 
</class> 


<class name="Address" batch-size="2" 


check="addressType in ('MAILING', 'HOME', 'BUSINESS')"> 


<composite-id> 
<key-many-to-one name="person" 
column="personName"/> 
<key-property name="type" 
column="addressType"/> 
</composite-id> 
<property name="Street" type="text"/> 
<property name="Sstate"/> 
<property name="zip"/> 
</class> 


23.4.2. Composite key example 


<class name="Customer"> 


<id name="customerId" 
length="10"> 
<generator class="assigned"/> 
</id> 


<property name="name" not-null="true" length="100"/> 
<property name="address" not-null="true" length="200"/> 


<list name="orders" 
inverse="true" 
cascade="Save-update"> 
<key column="customerId"/> 
<index column="orderNumber"/> 
<one-to-many class="Order"/> 
</list> 


</class> 


<class name="Order" table="CustomerOrder" lazy="true"> 
<synchronize table="LineItem"/> 
<synchronize table="Product"/> 


<composite-id name="id" 
class="Order$Id"> 
<key-property name="customerId" length="10"/> 
<key-property name="orderNumber"/> 
</composite-id> 


<property name="orderDate" 
type="calendar_date" 
not -null="true"/> 


<property name="total"> 
<formula> 
( select sum(1i.quantity*p.price) 
from LineItem li, Product p 
where 1i.productId = p.productId 
and 1i.customerId = customerId 
and 1i.orderNumber = orderNumber ) 
</formula> 
</property> 


<many-to-one name="Customer" 
column="customertId" 
insert="false" 


update="false" 
not-null="true"/> 


<bag name="lineItems" 
fetch="join" 
inverse="true" 
cascade="Save-update"> 
<key> 
<column name="customerId"/> 
<column name="orderNumber"/> 
</key> 
<one-to-many class="LineItem"/> 
</bag> 


</class> 


<class name="LineItem"> 


<composite-id name="id" 
class="LineItem$Id"> 
<key-property name="CcustomerId" length="10"/> 
<key-property name="orderNumber"/> 
<key-property name="productId" length="10"/> 


</composite-id> 
<property name="quantity"/> 


<many-to-one name="order" 
insert="false" 
update="false" 
not-null="true"> 
<column name="customerId"/> 
<column name="orderNumber"/> 
</many - to-one> 


<many-to-one name="product" 
insert="false" 
update="false" 
not -null="true" 
column="productIid"/> 


</class> 


<class name="Product"> 
<synchronize table="LineItem"/> 


<id name="productId" 

length="10"> 

<generator class="assigned"/> 
</id> 


<property name="description" 
not-null="true" 


length="200"/> 
<property name="price" length="3"/> 
<property name="numberAvailable"/> 


<property name="numberOrdered"> 
<formula> 
( select sum(1li.quantity) 
from LineItem li 
where 1li.productId = productId ) 
</formula> 
</property> 


</class> 


23.4.3. 共有 组 合 键 属性 的 多 对 多 (Many-to-many 
with shared composite key attribute) 


<class name="User" table=" User "> 
<composite-id> 
<key-property name="name"/> 
<key-property name="org"/> 
</composite-id> 
<set name="groups" table="UserGroup"> 
<key> 
<column name="userName"/> 
<column name="org"/> 
</key> 
<many-to-many class="Group"> 
<column name="groupName"/> 
<formula>org</formula> 
</many - to-many> 
</set> 
</class> 


<class name="Group" table=" Group "> 
<composite-id> 
<key-property name="name"/> 
<key-property name="org"/> 
</composite-id> 
<property name="description"/> 
<set name="users" table="UserGroup" inverse="true"> 
<key> 
<column name="groupName"/> 
<column name="org"/> 
</key> 
<many-to-many class="User"> 
<column name="userName"/> 
<formula>org</formula> 
</many - to-many> 
</set> 
</class> 


23.4.4. Content based discrimination 


<class name="Person" 
discriminator -value="P"> 


<id name="id" 
column="person_id" 
unsaved -value="0"> 
<generator class="native"/> 


</id> 
<discriminator 
type="character"> 
<formula> 
case 
when title is not null then 'E' 
when salesperson is not null then 'C' 
else 'P' 
end 
</formula> 
</discriminator> 


<property name="name" 
not-null="true" 
length="80"/> 


<property name="sex" 
not-null="true" 
update="false"/> 


<component name="address"> 
<property name="address"/> 
<property name="zip"/> 
<property name="country"/> 
</component> 


<subclass name="Employee" 
discriminator -value="E"> 
<property name="title" 
length="20"/> 
<property name="Salary"/> 
<many-to-one name="manager"/> 
</subclass> 


<subclass name="Customer" 
discriminator -value="C"> 
<property name="comments"/> 
<many-to-one name="Salesperson"/> 
</subclass> 


</class> 


23.4. 杂 例 
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23.4.5. Associations on alternate keys 


<class name="Person"> 


<id name="id"> 
<generator class="hilo"/> 
</id> 


<property name="name" length="100"/> 


<one-to-one name="address" 
property-ref="person" 
cascade="all" 
fetch="join"/> 


<set name="accounts" 
inverse="true"> 
<key column="userId" 
property-ref="userId"/> 
<one-to-many class="Account"/> 
</set> 


<property name="userId" length="8"/> 
</class> 
<class name="Address"> 
<id name="id"> 
<generator class="hilo"/> 
</id> 
<property name="address" length="300"/> 
<property name="Zzip" length="5"/> 
<property name="country" length="25"/> 
<many-to-one name="person" unique="true" not-null="true"/> 
</class> 
<class name="Account"> 
<id name="accountId" length="32"> 
<generator class="uuid"/> 
</id> 
<many-to-one name="user" 
column="userId" 
property-ref="userId"/> 


<property name="type" not-null="true"/> 


</class> 


23.4. 杂 例 
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第 24 章 最 佳 实践 (Best Practices) 


设计 细 颗 粒度 的 持久 类 并 且 使 用 &1t;component&gt; 来 实现 映射 。 


使 用 一 个 Address 持久 类 来 封装 street ，suburb ，state , postcode .这 
将 有 利于 代码 重用 和 简化 代码 重 构 (refactoring) 的 工作 。 


对 持久 类 声明 标识 符 属 性 ( identifier properties) ° 


Hibernate 中 标识 符 属性 是 可 选 的 ， 不 过 有 很 多 原因 来 说 明 你 应 该 使 用 标识 符 属 性 。 
我 们 建议 标识 符 应 该 是 "人 造 " 的 (自动 生成 ， 不 涉及 业务 含义 ) 。 


使 用 自然 键 (natural keys) 标 识 


对 所 有 的 实体 都 标识 出 自然 键 ， 用 &lt;natural-id&gt， 进 行 映射 。 实 
现 equals() 和 hashCode() ， 在 其 中 用 组 成 自然 键 的 属性 进行 比较 。 


为 每 个 持久 类 写 一 个 映射 文件 


不 要 把 所 有 的 持久 类 映射 都 写 到 一 个 大 文件 中 。 把 com.eg.Foo 了 映射 
到 com/eg/Foo.hbm.xml 中 ， 在 团队 开发 环境 中 ， 这 一 点 显得 特别 有 意义 。 


把 映射 文件 作为 资源 加 载 
把 映射 文件 和 他 们 的 映射 类 放 在 一 起 进行 部 署 。 
考虑 把 查询 字符 囊 放 在 程序 外 面 


如 果 你 的 查询 中 调用 了 非 ANSI 标 准 的 SQL 函数 ， 那 么 这 条 实践 经 验 对 你 适用 。 把 查 
询 字符 串 放 在 映射 文件 中 可 以 让 程序 具有 更 好 的 可 移植 性 。 


使 用 绑 定 变量 


就 像 在 JDBC 编 程 中 一 样 ， 应 该 总 是 用 占 位 符 "?" 来 蔡 换 非 常量 值 ， 不 要 在 查询 中 用 
字符 串 值 来 构造 非常 量 值 | 更 好 的 办 法 是 在 查询 中 使 用 命名 参数 。 

不 要 自己 来 管理 JDBC connections 

Hibernate 人 允许 应 用 程序 自己 来 管理 JDBC connections， 但 是 应 该 作为 最 后 没有 办 


法 的 办 法 。 如 果 你 不 能 使 用 Hibernate 内 建 的 connections providers， 那 么 考虑 实现 
自己 来 实现 org.hibernate.connection.ConnectionProvider 


考虑 使 用 用 户 自 定义 类 型 (custom type) 


假设 你 有 一 个 Java 类 型 ， 来 自 茶 些 类 库 ， 需 要 被 持久 化 ， 但 是 该 类 没有 提供 映射 操 
作 需 要 的 存 取 方 法 。 那 么 你 应 该 考虑 实现 org.hibernate.UserType 接口 。 这 种 
办 法 使 程序 代码 写 起 来 更 加 自如 ， 不 再 需要 考虑 类 与 Hibernate type 之 问 的 相互 转 
换 。 


在 性 能 瓶颈 的 地 方 使 用 硬 编码 的 JDBC 


In performance-critical areas of the system, some kinds of operations might 
benefit from direct JDBC. But please, wait until you know something is a 
bottleneck. And don't assume that direct JDBC is necessarily faster. If you need to 
use direct JDBC, it might be worth opening a Hibernate Session and using that 
JDBC connection. That way you can still use the same transaction strategy and 
underlying connection provider. 在 系统 中 对 性 能 要 求 很 严格 的 一 些 部 分 ， 某 些 操作 
也 许 直接 使 用 JDBC 会 更 好 。 但 是 请 先 确认 这 的 确 是 一 个 瓶颈 ， 并 且 不 要 想当然 认 
为 JDBC 一 定 会 更 快 。 如 果 确 实 需要 直接 使 用 JDBC， 那 么 最 好 打开 一 个 Hibernate 

Session 然后 从 Session 获得 connection， 按 照 这 种 办 法 你 仍然 可 以 使 用 同样 
的 transaction 策 略 和 底层 的 connection provider ° 


理解 Session 清洗 ( flushing) 


Session 会 不 时 的 向 数据 库 同步 持久 化 状态 ， 如 果 这 种 操作 进行 的 过 于 频繁 ， 性 能 
会 受到 一 定 的 影响 。 有 时 候 你 可 以 通过 禁止 自动 flushing， 尽 量 最 小 化 非 必 要 的 
flushing 操 作 ， 或 者 更 进一步 ， 在 一 个 特定 的 transaction 中 改变 查询 和 其 它 操 作 的 顺 
序 。 


在 三 层 结构 中 ， 考 虑 使 用 托管 对 象 (detached object) 


当 使 用 一 个 servlet / session bean 类 型 的 架构 的 时 候 , 你 可 以 把 已 加 载 的 持久 对 外 
在 session bean 层 和 servlet / JSP 层 之 间 来 回 传 递 。 使 用 新 的 session 来 为 每 个 请 求 
服务 ， 使 用 Session.merge() 或 者 Session.saveOrUpdate() 来 与 数据 库 同 
步 。 


在 两 层 结构 中 ， 考 虑 使 用 长 持久 上 下 文 (long persistence contexts). 


为 了 得 到 最 佳 的 可 伸缩 性 ， 数 据 库 事务 (Database Transaction) 应 该 尽 可 能 的 短 。 
但 是 ， 程 序 常常 需要 实现 长 时 间 运 行 的 “应 用 程序 事务 (Application Transaction)” > 
包含 一 个 从 用 户 的 观点 来 看 的 原子 操作 。 这 个 应 用 程序 事务 可 能 跨越 多 次 从 用 户 请 
求 到 得 到 反馈 的 循环 。 用 脱 管 对 象 (与 session 脱离 的 对 象 ) 来 实现 应 用 程序 事务 是 常 
见 的 。 或 者 ， 尤 其 在 两 层 结构 中 ， 把 Hibernate Session 从 JDBC 连 接 中 脱离 开 ， 下 
次 需要 用 的 时 候 再 连接 上 。 绝 不 要 把 一 个 Session 用 在 多 个 应 用 程序 事务 
(Application Transaction) 中 ， 否 则 你 的 数据 可 能 会 过 期 失效 。 


不 要 把 异常 看 成 可 恢复 的 


这 一 点 其 至 比 “ 最 佳 实践 "还 要 重要 ， 这 是 " 必 备 常识 "。 当 异常 发 生 的 时 候 ， 必 须要 回 
XÈ Transaction ， 关 闭 Session 。 如 果 你 不 这 样 做 的 话 ，Hibernate 无 法 保证 
内 存 状 态 精 确 的 反应 持久 状态 。 尤 其 不 要 使 用 Session.load() 来 判断 一 个 给 定 
标识 符 的 对 象 实例 在 数据 库 中 是 否 存 在 ， 应 该 使 用 Session.get() 或 者 进行 一 次 
查询 . 


对 于 关联 优先 考虑 lazy fetching 


谨 懂 的 使 用 主动 抓 取 (eager fetching)。 对 于 关联 来 说 ， 若 其 目标 是 无 法 在 第 二 级 缓 
存 中 完全 缓存 所 有 实例 的 类 ， 应 该 使 用 代理 (proxies) 与 /或 具有 延迟 加 载 属性 的 集合 
(lazy collections)。 若 目标 是 可 以 被 缓存 的 ， 尤 其 是 缓存 的 命中 率 非 常 高 的 情况 下 ， 
应 该 使 用 lazy="false" ， 明 确 的 禁止 掉 eager fetching。 如 果 那 些 特殊 的 确实 适 

合 使 用 join fetch 的 场合 ， 请 在 查询 中 使 用 left join fetch 。 


使 用 open session in View 模式， 或 者 执行 严格 的 装配 期 (assembly phase) 策 略 来 避 
免 再 次 抓 取 数 据 带 来 的 问题 


Hibernate 让 开发 者 们 摆脱 了 繁琐 的 Data Transfer Objects (DTO)。 在 传统 的 EJB 结 
构 中 ，DTO 有 双重 作用 : 首先 ， 他 们 解决 了 entity bean 无 法 序列 化 的 问题 ; 其 次 ， 
他 们 隐 含 地 定义 了 一 个 装配 期 ， 在 此 期 间 ， 所 有 在 view 层 需要 用 到 的 数据 ， 都 被 抓 
取 、 集 中 到 了 DTO 中 ， 然 后 控制 才 被 装 到 表示 层 。Hibernate 终 结 了 第 一 个 作用 。 
然而 ， 除 非 你 做 好 了 在 整个 泻 染 过 程 中 都 维护 一 个 打开 的 持久 化 上 下 文 (session) 的 
约 ， 数 据 总 是 被 放置 到 托管 对 象 中 ) 。 这 并 非 是 Hibernate 的 限制 ! 这 是 实现 安全 的 
事务 化 数据 访问 的 基本 需求 。 


考虑 把 Hibernate 代 码 从 业务 逻辑 代码 中 抽象 出 来 


把 Hibernate 的 数据 存 取代 码 隐 藏 到 接口 (interface) 的 后 面 ， 组 合 使 用 DAO 和 Thread 
Local Session 模 式 。 通 过 Hibernate 的 UserType ， 你 甚至 可 以 用 硬 编码 的 JDBC 
来 持久 化 那些 本 该 被 Hibernate 持 久 化 的 类 。 (该 建议 更 适用 于 规模 足够 大 应 用 软件 
中 ， 对 于 那些 只 有 5 张 表 的 应 用 程序 并 不 适合 。) 


不 要 用 怪异 的 连接 映射 


多 对 多 连接 用 得 好 的 例子 实际 上 相当 少见 。 大 多 数 时 候 你 在 “连接 表 " 中 需要 保存 额 
外 的 信息 。 这 种 情况 下 ， 用 两 个 指向 中 介 类 的 一 对 多 的 连接 比较 好 。 实 际 上 ， 我 们 
认为 绝 大 多 数 的 连接 是 一 对 多 和 多 对 一 的 ， 你 应 该 谨 懂 使 用 其 它 连接 风格 ， 用 之 前 
问 自己 一 句 ， 是 否 丨 的 必须 这 么 做 。 


偏爱 双向 关联 


单 向 关联 和 更 加 难于 查询 。 在 大 型 应 用 中 ， 几 乎 所 有 的 关联 必须 在 查询 中 可 以 双向 导 
航 。 


HttpClient 教程 


Ai 译 


超 文本 传输 协议 (HTTP) 也 许 是 当今 互联 网 上 使 用 的 最 重要 的 协议 了 。Web 服 
务 ， 有 网 络 功能 的 设备 和 网 络 计 算 的 发 展 ， 都 持续 扩展 了 HTTP 协 议 的 角色 ， 超 越 
了 用 户 使 用 的 Web 浏 览 器 范畴 ， 同 时 ， 也 增加 了 需要 HTTP 协 议 支 持 的 应 用 程序 的 
数量 。 


尽管 java.net 包 提供 了 基本 通过 HTTP 访 问 资源 的 功能 ， 但 它 没有 提供 全 面 的 灵活 性 
和 其 它 很 多 应 用 程序 需要 的 功能 。HttpClient 就 是 寻求 弥补 这 项 空白 的 组 件 ， 通 过 提 
供 一 个 有 效 的 ， 保 持 更 新 的 ， 功 能 丰富 的 软件 包 来 实现 客户 端 最 新 的 HTTP 标 准 和 
建议 。 


为 扩展 而 设计 ， 同 时 为 基本 的 HTTP 协 议 提供 强大 的 支持 ，HttpClient 组 件 也 许 就 是 
构建 HTTP 客 户 端 应 用 程序 ， 比 如 Web 浏 览 器 ，web 服 务 端 ， 利 用 或 扩展 HTTP 协 议 
进行 分 布 式 通信 的 系统 的 开发 人 员 的 关注 点 。 


1. HttpClient 的 范围 


e 基于 HttpCore 的 客户 端 HTTP 运 输 实 现 库 
。 基于 经 典 (阻塞 ) VO 
e 内 容 无 关 


2. 什么 是 HttpClient 不 能 做 的 


e HttpClient 不 是 一 个 浏览 器 。 它 是 一 个 客户 端的 HTTP 通 信和 实现 库 。HttpClient 的 
目标 是 发 送 和 接收 HTTP 报 文 。HttpClient 不 会 去 缓存 内 容 ， 执 行 虐 入 在 HTML 
页 面 中 的 javascript 代 码 ， 猜 测 内 容 类 型 ， 重 新 格式 化 请 求 / 重 定向 URI， 或 者 其 
它 和 HTTP 和 运输 无 关 的 功能 。 


关于 翻译 


本 文档 翻译 工作 由 南 需 完成 ， 版 权 归 译 者 所 有 。 免 费 发 布 ， 但 是 不 可 擅自 用 于 任何 
SA 业 有 关 的 用 途 。 若 对 翻译 质量 有 任何 意见 或 建议 ， 可 以 联系 译 者 
nanlei1987@gmail.com 。 美文 原版 由 Oleg Kalnichevski 所 著 ， 若 对 HttpClient 
本 身 有 问题 的 可 以 直接 反馈 到 Apache È 网 HttpClient 项 目 组 


第 一 章 基础 


1.1 执行 请 求 


HttpClient 最 重要 的 功能 是 执行 HTTP 方 法 "一 个 HTTP 方 法 的 执行 包含 一 ENAT 
HTTP 请 求 /HTTP 响 应 交换 ， 通 常 由 HttpClient 的 内 部 来 处 理 。 而 期 望 用 户 提供 一 个 
要 执行 的 请 求 对 象 ， 而 HttpClient 期 望 传输 请 求 到 目标 服务 器 并 返回 对 应 的 响应 对 
象 ， 或 者 当 执行 不 成 功 时 抛 出 异常 。 


很 自然 地 ，HttpClient API 的 主要 切入 点 就 是 定义 描述 上 述 规约 的 HttpClient 接 口 。 
这 里 有 一 个 很 简单 的 请 求 执 行 过 程 的 示例 : 


HttpClient httpclient = new DefaultHttpClient(); 
HttpGet httpget = new HttpGet("http://localhost/"); 
HttpResponse response = httpclient.execute(httpget); 
HttpEntity entity = response.getEntity(); 
if (entity != null) { 

InputStream instream = entity.getContent(); 


int 1; 
byte[] tmp = new byte[2048]; 
while (( = instream.read(tmp)) != -1) { 


1.1.1 HTTP ia R 
所 有 HTTP 请 求 有 一 个 组 合 了 方法 名 ， 请 求 URI 和 HTTP 协 议 版 本 的 请 求 行 。 


HttpClient 支 持 所 有 定义 在 HTTP/1.1 版 本 中 的 HTTP 方 法 : GET > HEAD > POST ， 
PUT > DELETE > TRACE#*OPTIONS 。 对 于 每 个 方法 类 型 都 有 一 个 特殊 的 类 : 
HttpGet > HttpHead > HttpPost > HttpPut > HttpDelete > HttpTrace 和 HttpOptions ° 


请 求 的 URI 是 统一 资源 定位 符 ， 它 标识 了 应 用 于 哪个 请 求 之 上 的 资源 。HTTP 请 求 
URI 包 含 一 个 协议 模式 ， 主 机 名 称 ， 可 选 的 端口 ， 资 源 路 径 ， 可 选 的 查询 和 可 选 的 
片段 。 


HttpGet httpget = new HttpGet( 
"http://www. google.com/search?hl=en&q=httpclient&btnG=Google 


+Search&aq=f&oq=") ; 


HttpClient 提 供 很 多 工具 方法 来 简化 创建 和 修改 执行 URI。 URI 也 可 以 编程 来 拼装 


URI uri = URIUtils.createURI("http", "www.google.com", -1, "/sea 
KENN, 

"q=httpclient&btnG=Google+Search&aq=f&oq=", null); 
HttpGet httpget = new HttpGet(uri); 
System.out.println(httpget.getURI()); 


输出 内 容 为 : 


http://www. google.com/search?q=httpclient&btnG=Google+Search&aq= 
f&od= 


查询 字符 串 也 可 以 从 独立 的 参数 中 来 生成 : 


List<NameValuePair> qparams = new ArrayList<NameValuePair>(); 
qparams.add(new BasicNameValuePair("q", "httpclient")); 
qparams.add(new BasicNameValuePair("btnG", "Google Search")); 
qparams.add(new BasicNameValuePair("aq", "f")); 

qparams.add(new BasicNameValuePair("og", null)); 

URI uri = URIUtils.createURI("http", "www.google.com", -1, "/sea 
ren 

URLEncodedUtils.format(qparams, "UTF-8"), null); 

HttpGet httpget = new HttpGet(uri); 
System.out.printin(httpget.getURI()); 


输出 内 容 为 : 


http://www. google .com/search?q=httpclient&btnG=Google+Search&aq= 
f&oq= 


1.1.2 HTTP 响 应 


HTTP 响 应 是 由 服务 器 在 接收 和 解释 请 求 报 文 之 后 返回 发 送 给 客户 端的 报 文 。 响 应 
报 文 的 第 一 行 包 含 了 协议 版 本 ， 之 后 是 数字 状态 码 和 相关 联 的 文本 段 。 


HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1 
ek, 
HttpStatus.SC_OK, "OK"); 
System.out.println(response.getProtocolVersion()); 
System.out.println(response.getStatusLine().getStatusCode()); 
System.out.println(response.getStatusLine().getReasonPhrase()); 


System.out.println(response.getStatusLine().toString()); 


输出 内 容 为 : 


HTTP/1.14 

200 

OK 

HTTP/1.1 200 OK 


1.1.3 处 理 报 文 头 部 
一 个 HTTP 报 文 可 以 包含 很 多 描述 如 内 容 长 度 ， 内 容 类 型 等 信息 属性 的 头 部 信息 。 
HttpClient 提 供 获取 ， 添 加 ， 移 除 和 枚 举 头 部 信息 的 方法 。 


HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1 
aul, 

HttpStatus.SC_OK, "OK"); 
response. addHeader ("Set-Cookie", 

"c1=a; path=/; domain=localhost"); 
response. addHeader ("Set-Cookie", 

"C2=b; path=\"/\", c3=c; domain=\"localhost\""); 
Header h1 = response.getFirstHeader ("Set-Cookie"); 
System.out.printin(h1); 

Header h2 = response.getLastHeader ("Set-Cookie"); 
System.out.printiln(h2); 

Header[] hs = response.getHeaders("Set-Cookie"); 
System.out.println(hs.length); 


输出 内 容 为 : 


Set-Cookie: ci=a; path=/; domain=localhost 
Set-Cookie: c2=b; path="/", c3=c; domain="localhost" 


获得 给 定 类 型 的 所 有 头 部 信息 最 有 效 的 方式 是 使 用 Headerlterator 接 口 。 


HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1 
aly 

HttpStatus.SC_OK, "OK"); 
response. addHeader ("Set-Cookie", 

"c1=a; path=/; domain=localhost"); 
response. addHeader ("Set-Cookie", 

"C2=b; path=\"/\", c3=c; domain=\"localhost\""); 
HeaderIterator it = response.headerIterator ("Set-Cookie"); 
while (it.hasNext()) { 

System.out.printin(it.next()); 

} 


输出 内 容 为 : 


Set-Cookie: ci=a; path=/; domain=localhost 


Set-Cookie: c2=b; path="/", c3=c; domain="localhost" 


它 也 提供 解析 HTTP 报 文 到 独立 头 部 信息 元 素 的 方法 方法 。 


HttpResponse response = new BasicHttpResponse(HttpVersion.HTTP_1 


ky 
HttpStatus.SC_OK, "OK"); 
response. addHeader ("Set-Cookie", 
"c1=a; path=/; domain=localhost"); 
response. addHeader ("Set-Cookie", 


"c2=b; path=\"/\", c3=c; domain=\"localhost\""); 


HeaderElementiIterator it = new BasicHeaderElementIterator ( 


response.headerIterator("Set-Cookie") ); 
while (it.hasNext()) { 
HeaderElement elem = it.nextElement(); 


System.out.println(elem.getName() + " = " + elem.getValue() ) 


NameValuePair[] params = elem.getParameters(); 
for (int i = 0; i < params.length; i++) { 
System.out.printin(" " + params[i]); 


} 


输出 内 容 为 : 


cl=a 
path=/ 
domain=localhost 
c2 = b 
path=/ 
c3 =c 
domain=localhost 


1.1.4 HTTP 4% 


HTTP 报 文 可 以 携带 和 请 求 或 响应 相关 的 内 容 实 体 。 实 体 可 以 在 一 些 请 求 和 响应 中 
找到 ， 因 为 它们 也 是 可 选 的 。 使 用 了 实体 的 请 求 被 称 为 封 闭 实体 请 求 。HTTP 规 范 
定义 了 两 种 封闭 实体 的 方法 : POST 和 PUT。 响 应 通常 期 望 包 含 一 个 内 容 实 体 。 这 
个 规则 也 有 特例 ， 比 如 HEAD 方 法 的 响应 和 204 No Content > 304 Not Modified 和 


205 Reset Content 响 应 。 
HttpClient 根 据 其 内 容 出 自 何 处 区 分 三 种 类 型 的 实体 : 
e streamed 流 式 : 内 容 从 流 中 获得 ， 或 者 在 运行 中 产生 。 特 别 是 
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这 种 


分 类 


HTTP 响 应 中 获取 的 实体 。 流 式 实 体 是 不 可 重复 生成 的 。 
e self-contained A REZA : 内 容 在 内 存 中 或 通过 独立 的 连接 或 其 它 实 体 中 获 
得 。 自 我 包含 式 的 实体 是 可 以 重复 生成 的 。 这 种 类 型 的 实体 会 经 常用 于 封闭 
HTTP 请 求 的 实体 。 
e wrapping 包 装 式 : 内 容 从 另外 一 个 实体 中 获得 。 


当 从 一 个 HTTP 响 应 中 获取 流 式 内 容 时 ， 这 个 区 别 对 于 连接 管理 很 重要 。 对 于 由 应 
用 程序 创建 而 且 只 使 用 HttpClient 发 送 的 请 求实 体 ， 流 式 和 自我 包含 式 的 不 同 就 不 那 
么 重要 了 。 这 种 情况 下 ， 建 议 考 虑 如 流 式 这 种 不 能 重复 的 实体 ， 和 可 以 重复 的 自我 
包含 式 实体 。 


1.1.4.1 重复 实体 


实体 可 以 重复 ， 意 味 着 它 的 内 容 可 以 被 多 次 读 取 。 这 就 仅仅 是 自我 包含 式 的 实体 了 
( 像 ByteArrayEntity 或 StringEntity) 。 


1.1.4.2 使 用 HTTP 实 体 


因为 一 个 实体 既 可 以 代表 二 进 制 内 容 又 可 以 代表 字符 内 容 ， 它 也 支持 字符 编码 ( 支 
持 后 者 也 就 是 字符 内 容 ) 。 


实体 是 当 使 用 封闭 内 容 执 行 请 求 ， 或 当 请 求 已 经 成 功 执 行 ， 或 当 响 应 体 结 果 发 功 到 
客户 端 时 创建 的 。 


要 从 实体 中 读 取 内 容 ， 可 以 通过 HttpEntity#getContent() 方 法 从 输入 流 中 获取 ， 这 
会 返回 一 个 java.io.InputStream 对 象 ， 或 者 提供 一 个 输出 流 到 
HttpEntity#writeTo(OutputStream) 方 法 中 ， 这 会 一 次 返回 所 有 写 入 到 给 定 流 中 的 内 


当 实 体 通 过 一 个 收 到 的 报 文 获取 时 ，HttpEntity#getContentType() 方 法 和 
HttpEntity#getContentLength() 方 法 可 以 用 来 读 取 通用 的 元 数据 ， 如 Content-Type 
和 Content-Length 头 部 信息 (如 果 它 们 是 可 用 的 ) 。 因 为 头 部 信息 Content-Type 可 
以 包含 对 文本 MIME 类 型 的 字符 编码 ， 比 如 text/plain 或 text/html > 
HttpEntity#getContentEncoding() 方 法 用 来 读 取 这 个 信息 。 如 果 头 部 信息 不 可 用 ， 
那么 就 返回 长 度 -1， 而 对 于 内 容 类 型 返回 NULL。 如 果 头 部 信息 Content-Type 是 可 
用 的 ， 那 么 就 会 返回 一 个 Header 对 象 。 


当 为 一 个 传 出 报 文 创建 实体 时 ， 这 个 元 数据 不 得 不 通过 实体 创建 器 来 提供 。 


StringEntity myEntity = new StringEntity("important message", 
"UTF-8"); 

System.out.println(myEntity.getContentType()); 

System.out.println(myEntity.getContentLength()); 

System.out.printin(EntityUtils.getContentCharSet(myEntity) ); 

System.out.printin(EntityUtils.toString(myEntity) ); 

System.out.printin(EntityUtils.toByteArray(myEntity).length); 


输出 内 容 为 
Content-Type: text/plain; charset=UTF-8 17 UTF-8 important message 17 


1.1.5 确保 低级 别 资源 释放 


当 完 成 一 个 响应 实体 ， 那 么 保证 所 有 实体 内 容 已 经 被 完全 消耗 是 很 重要 的 ， 所 以 连 
接 可 以 安全 的 放 回 到 连接 池 中 ， 而 且 可 以 通过 连接 管理 器 对 后 续 的 请 求 重用 连接 。 
处 理 这 个 操作 的 最 方便 的 方法 是 调用 HttpEntity#tconsumeContent() 方 法 来 消耗 流 中 
的 任意 可 用 内 容 。HttpClient 探 测 到 内 容 流 尾 部 已 经 到 达 后 ， 会 立即 会 自动 释放 低层 
连接 ， 并 放 回 到 连接 管理 器 。HttpEntity#consumeContent() 方 法 调用 多 次 也 是 安全 
的 。 


也 可 能 会 有 特殊 情况 ， 当 整个 响应 内 容 的 一 小 部 分 需要 获取 ， 消 耗 剩余 内 容 而 损失 
性 能 ， 还 有 重用 连接 的 代价 太 高 ， 则 可 以 仅仅 通过 调用 HttpUriRequest#abort() 方 法 
来 中 止 请 求 。 


HttpGet httpget = new HttpGet("http://localhost/"); 
HttpResponse response = httpclient.execute(httpget); 
HttpEntity entity = response.getEntity(); 
if (entity != null) { 

InputStream instream = entity.getContent(); 

int byteOne = instream.read(); 

int byteTwo = instream.read(); 

// Do not need the rest 

httpget.abort(); 


连接 不 会 被 重用 ， 但 是 由 它 持 有 的 所 有 级 别 的 资源 将 会 被 正确 释放 。 


1.1.6 消耗 实体 内 容 


推荐 消耗 实体 内 容 的 方式 是 使 用 它 的 HttpEntity#getContent() 或 
HttpEntity#writeTo(OutputStream) 方 法 。HttpClient 刀 自 带 EntityUtils 类 ， 这 会 暴露 
出 一 些 静 态 方法 ， 这 些 方法 可 以 更 加 容易 地 从 实体 中 读 取 内 容 或 信息 。 代 替 直 接 读 
取 java.io.InputStream， 也 可 以 使 用 这 个 类 中 的 方法 以 字符 串 / 字 节 数 组 的 形式 获取 
整个 内 容 体 。 然 而 ，EntityUtils 的 使 用 是 强烈 不 鼓励 的 ， 除 非 响应 实体 源 自 可 靠 的 
HTTP 服 务 器 和 已 知 的 长 度 限制 。 


HttpGet httpget = new HttpGet("http://localhost/"); 
HttpResponse response = httpclient.execute(httpget); 
HttpEntity entity = response.getEntity(); 
if (entity != null) { 

long len = entity.getContentLength(); 


if (len != -1 && len < 2048) { 
System.out.printin(EntityUtils.toString(entity) ); 
} else { 


// Stream content out 


} 


在 一 些 情况 下 可 能 会 不 止 一 次 的 读 取 实 体 。 此 时 实体 内 容 必 须 以 某 种 方式 在 内 存 或 
磁盘 上 被 缓冲 起 来 。 最 简单 的 方法 是 通过 使 用 BufferedHttpEntity 类 来 包装 源 实体 完 
成 。 这 会 引起 源 实 体内 容 被 读 取 到 内 存 的 缓冲 区 中 。 在 其 它 所 有 方式 中 ， 实 体 包 装 
器 将 会 得 到 源 实体 。 


HttpGet httpget = new HttpGet("http://localhost/"); 
HttpResponse response = httpclient.execute(httpget); 
HttpEntity entity = response.getEntity(); 
if (entity != null) { 

entity = new BufferedHttpEntity(entity); 
} 


1.1.7 生成 实体 内 容 


HttpClient 提 供 一 些 类 ， 它 们 可 以 用 于 生成 通过 HTTP 连 接 获 得 内 容 的 有 效 输 出 流 。 
为 了 封闭 实体 从 HTTP 请 求 中 获得 的 输出 内 容 ， 那 些 类 的 实例 可 以 和 封闭 如 POST 和 
PUT 请 求 的 实体 相关 联 。HttpClient 为 很 多 公用 的 数据 容器 ， 比 如 字符 串 ， 字 节 数 
组 ， 输 入 流 和 文件 提供 了 一 些 类 : StringEntity，ByteArrayEntity > 
InputStreamEntity 和 FileEntity 。 


File file = new File("somefile.txt"); 

FileEntity entity = new FileEntity(file, "text/plain; charset=\" 
UTF-8\""); 

HttpPost httppost = new HttpPost("http://localhost/action.do"); 
httppost.setEntity(entity); 


请 注意 InputStreamEntity 是 不 可 重复 的 ， 因 为 它 仅 仅 能 从 低层 数据 流 中 读 取 一 次 内 
容 。 通 常 来 说 ， 我 们 推荐 实现 一 个 定制 的 HttpEntity 类 ， 这 是 自我 包含 式 的 ， 用 来 代 
替 使 用 通用 的 InputStreamEntity。FileEntity 也 是 一 个 很 好 的 起 点 。 


1.1.7.1 动态 内 容 实体 


通常 来 说 ，HTTP 实 体 需 要 基于 特定 的 执行 上 下 文 来 动态 地 生成 。 通 过 使 用 
EntityTemplate 实 体 类 和 ContentProducer 接 口 ，HttpClient 提 供 了 动态 实体 的 支 

持 。 内 容 生 成 器 是 按照 需求 生成 它们 内 容 的 对 象 ， 将 它们 写 入 到 一 个 输出 流 中 。 它 
们 是 每 次 被 请 求 时 来 生成 内 容 。 所 以 用 EntityTemplate 创 建 的 实体 通常 是 自我 包含 
而 且 可 以 重复 的 。 


ContentProducer cp = new ContentProducer() { 
public void writeTo(OutputStream outstream) throws IOExcepti 
on { 
Writer writer = new OutputStreamWriter(outstream, "UTF-8 
"); 
writer.write("<response>"); 
writer.write(" <content>"); 
writer.write(" important stuff"); 
writer.write(" </content>"); 
writer.write("</response>"); 
writer.flush(); 
} 
}; 
HttpEntity entity = new EntityTemplate(cp); 
HttpPost httppost = new HttpPost("http://localhost/handler.do"); 
httppost.setEntity(entity); 


1.1.7.2 HTML 表 单 


许多 应 用 程序 需要 频繁 模拟 提交 一 个 HTML 表 单 的 过 程 ， 比 如 ， 为 了 来 记录 一 个 
Web 应 用 程序 或 提交 输出 数据 。 HIPC lene 了 特殊 的 实体 类 
UrIEncodedFormEntity 来 这 个 满足 过 程 。 


List<NameValuePair> formparams = new ArrayList<NameValuePair>(); 
formparams.add(new BasicNameValuePair("parami", "valuei")); 
formparams.add(new BasicNameValuePair("param2", "value2")); 
UrlEncodedFormEntity entity = new UrlEncodedFormEntity(formparam 
s, "UTF-8"); 

HttpPost httppost = new HttpPost("http://localhost/handler.do"); 
httppost.setEntity(entity); 


UrlEncodedFormEntity 实 例 将 会 使 用 URL 编 码 来 编码 参数 ， 生 成 如 下 的 内 容 : 


parami=value1&param2=value2 


1.1.7.3 内 容 分 块 


通常 ， 我 们 推荐 让 HttpClient 选 择 基于 被 传递 的 HTTP 报 文 属性 的 最 适合 的 编码 转 
换 。 这 是 可 能 的 ， Vek > it Htpentiy#setChunked()> 2 Arue t i #HtpClieni 
分 块 编码 的 首选 。 请 注意 HttpClient 将 会 使 用 标识 作为 提示 。 当 使 用 的 HTTP 协 议 版 
本 ， 如 HTTP/1.0 版 本 ， 不 支持 分 块 编码 时 ， 这 个 值 会 被 忽略 。 


StringEntity entity = new StringEntity("important message", 
"text/plain; charset=\"UTF-8\""); 

entity.setChunked(true); 

HttpPost httppost = new HttpPost("http://localhost/acrtion.do"); 

httppost.setEntity(entity); 


也 


1.1.8 响应 控制 器 


控制 响应 的 最 简便 和 最 方便 的 方式 是 使 用 ResponseHandler 接 口 。 这 个 放 完 完全 减 
轻 了 用 户 关 于 连接 管理 的 担心 。 当 使 用 ResponseHandler 时 ，HttpClient 将 会 自动 关 
注 并 保证 释放 连接 到 连接 管理 器 中 去 ， 而 不 管 请 求 执行 是 否 成 功 或 引发 了 异常 。 


HttpClient httpclient = new DefaultHttpClient(); 
HttpGet httpget = new HttpGet("http://localhost/"); 
ResponseHandler<byte[]> handler = new ResponseHandler<byte[ ]>() 


public byte[] handleResponse( 
HttpResponse response) throws ClientProtocolException, IOExc 
eption { 
HttpEntity entity = response.getEntity(); 
if (entity != null) { 
return EntityUtils.toByteArray(entity); 
} else { 
return null; 
} 


} 
}; 
byte[] response = httpclient.execute(httpget, handler); 


1.2 HTTP 执 行 的 环境 


最 初 ，HTTP 是 被 设计 成 无 状态 的 ， 面 向 请 求 -响应 的 协议 。 然 而 ， 旦 实 的 应 用 程序 
经 常 需要 通过 一 些 逻 辑 相 关 的 请 求 -响应 交换 来 持久 状态 信息 。 为 了 开启 应 用 程序 来 
维持 一 个 过 程 状 态 ，HttpClient 允 许 HTTP 请 求 在 一 个 特定 的 执行 环境 中 来 执行 ， 简 
称 为 HTTP 上 下 文 。 如 果 相 同 的 环境 在 连续 请 求 之 间 重 用 ， 那 么 多 种 逻辑 相关 的 请 
求 可 以 参与 到 一 个 逻辑 会 话 中 。HTTP 上 下 文 功 能 和 java.util.Map<String,Object> 很 
相似 。 它 仅仅 是 任意 命名 参数 值 的 集合 。 应 用 程序 可 以 在 请 求 之 前 或 在 检查 上 下 文 
执行 完成 之 后 来 填充 上 下 文 属性 。 


在 HTTP 请 求 执行 的 这 一 过 程 中 ，HttpClient 添 加 了 下 列 属 性 到 执行 上 下 文中 : 


e http.connection : HttpConnection 实 例 代 表 了 连接 到 目标 服务 器 的 趴 实 连 
接 。 

e http.target_host : HttpHost 实 例 代 表 了 连接 目标 。 

e http.proxy_host : 如 果 使 用 了 ，HttpHost 实 例 代 表 了 代理 连接 。 

e http.request : HttpRequest& #] XA T AE iHTTP RK ° 


e http.response : HttpResponse È #] (LA T AK AHTTP © 
e http.request_sent : java.lang.Booleant RAAT m A ERAT 
全 传送 到 目标 连接 的 标识 。 


比如 ， 为 了 决定 最 终 的 重 定向 目标 ， 在 请 求 执 行 之 后 ， 可 以 检查 http.target_host 属 
性 的 值 : 


让 


DefaultHttpClient httpclient = new DefaultHttpClient(); 
HttpContext localContext = new BasicHttpContext(); 
HttpGet httpget = new HttpGet("http://www.google.com/"); 
HttpResponse response = httpclient.execute(httpget, localContext 
); 
HttpHost target = (HttpHost) localContext.getAttribute( 
ExecutionContext .HTTP_TARGET_HOST ) ; 
System.out.printin("Final target: " + target); 
HttpEntity entity = response.getEntity(); 
if (entity != null) { 
entity.consumeContent(); 
} 


输出 内 容 为 : 


Final target: http://www.google.ch 


1.3 HAE 


HttpClient 能 够 抛 出 两 种 类 型 的 异常 : 在 IJO 失 败 时 ， 如 和 套 接 字 连 接 超时 或 被 重 置 的 
java.io.IOException 弄 常 ， 还 有 标志 HTTP 请 求 失败 的 信号 ， 如 违反 HTTP 协 议 的 
HttpException 异 常 。 通 常 |/O 错 误 被 认为 是 非 致命 的 和 可 以 恢复 的 ， 而 HTTP 协 议 错 
误 则 被 认为 是 致命 的 而 且 是 不 能 自动 恢复 的 。 


1.3.1 HTTP 运 输 安 全 


要 理解 HTTP 协 议 并 不 是 对 所 有 类 型 的 应 用 程序 都 适合 的 ， 这 一 点 很 重要 。HTTP 是 
一 个 简单 的 面向 请 求 / 响 应 的 协议 ， 最 初 被 设计 用 来 支持 取 回 静态 或 动态 生成 的 内 

容 。 它 从 未 向 支持 事务 性 操作 方向 发 展 。 比 如 ， 如 果 成 功 收 到 和 处 理 请 求 ，HTTP 
服务 器 将 会 考虑 它 的 其 中 一 部 分 是 否 完 成 ， 生 成 一 个 响应 并 发 送 一 个 状态 码 到 客户 
端 。 如 果 客 户 端 因为 读 取 超时 ， 请 求 取 消 或 系统 崩溃 导致 接收 响应 实体 失败 时 ， 服 
务 器 不 会 试图 回 滚 事务 。 如 果 客 户 端 决定 重新 这 个 请 求 ， 那 么 服务 器 将 不 可 避免 地 
不 止 一 次 执行 这 个 相同 的 事务 。 在 一 些 情况 下 ， 这 会 导致 应 用 数据 损坏 或 者 不 一 致 
的 应 用 程序 状态 。 


尽管 HTTP 从 来 都 没有 被 设计 来 支持 事务 性 处 理 ， 但 它 也 能 被 用 作 于 一 个 传输 协议 
对 关键 的 任务 应 用 提供 被 满足 的 确定 状态 。 要 保证 HTTP 传 输 层 的 安全 ， 系 统 必 须 
保证 HTTP 方 法 在 应 用 层 的 千 等 性 。 


1.3.2 FEW AK 
HTTP/1.1 明确 地 定义 了 有 老 等 的 方法 ， 描 述 如 下 
方法 也 可 以 有 " 震 等 "属性 在 那些 (除了 错误 或 过 期 问题 ) N 的 副作用 >0 的 相同 
请 求 和 独立 的 请 求 是 相同 的 
换 名 话说 ， 应 用 程序 应 该 保证 准备 着 来 处 理 多 个 相同 方法 执行 的 实现 。 这 是 可 以 达 
到 的 ， 比 如 ， 通 过 提供 一 个 独立 的 事务 ID 和 其 它 避 免 执 行 相 同 逻 辑 操作 的 方法 。 


请 注意 这 个 问题 对 于 HttpClient 是 不 具体 的 。 基 于 应 用 的 浏览 器 特别 受 和 非 需 等 的 
HTTP 方 法 相关 的 相同 问题 的 限制 。 


HttpClient 假 设 没 有 实体 包含 方法 ， 比 如 GET 和 HEAD 是 寺 等 的 ， 而 实体 包含 方法 ， 
比如 POST 和 PUT 则 不 是 。 


1.3.3 异常 自动 恢复 


默认 情况 下 ，HttpClient 会 试图 自动 从 MO 异常 中 恢复 。 默 认 的 自动 恢复 机 制 是 受 很 
少 一 部 分 已 知 的 异常 是 安全 的 这 个 限制 。 


e HttpClient 不 会 从 任意 逻辑 或 HTTP 协 议 错误 (那些 是 从 HttpException 类 中 派生 
出 的 ) 中 恢复 的 。 

e HttpClient 将 会 自动 重新 执行 那么 假设 是 需 等 的 方法 。 

e HttpClient 将 会 自动 重新 执行 那些 由 于 运输 异常 失败 ， 而 HTTP 请 求 仍 然 被 传送 
到 目标 服务 器 〈 也 就 是 请 求 没 有 完全 被 送 到 服务 器 ) 失败 的 方法 。 

e HttpClient 将 会 自动 重新 执行 那些 已 经 完全 被 送 到 服务 器 ， 但 是 服务 器 使 用 
HTTP 状 态 码 (服务 器 仅仅 丢掉 连接 而 不 会 发 回 任何 东西 ) 响应 时 失败 的 方 
法 。 在 这 种 情况 下 ， 假 设 请 求 没有 被 服务 器 处 理 ， 而 应 用 程序 的 状态 也 没有 改 
变 。 如 果 这 个 假设 可 能 对 于 你 应 用 程序 的 目标 Web 服 务 器 来 说 不 正确 ， 那 么 就 
强烈 建议 提供 一 个 自 定义 的 异常 处 理 器 。 


1.3.4 请 求 重 试 处 理 


为 了 开启 自 定 义 异 常 恢 复 机 制 ， 应 该 提供 一 个 HttpRequestRetryHandler 接 口 的 实 
现 。 


DefaultHttpClient httpclient = new DefaultHttpClient(); 
HttpRequestRetryHandler myRetryHandler = new HttpRequestRetryHan 
dler() { 
public boolean retryRequest(IOException exception, 
int executionCount,HttpContext context) { 
if (executionCount >= 5) { 
// 如 果 超 过 最 大 重 试 次 数 ， 那 么 就 不 要 继续 了 
return false; 


if (exception instanceof NoHttpResponseException) { 
// 如 果 服 务 器 丢掉 了 连接 ， 那 么 就 重 试 
return true; 


} 

if (exception instanceof SSLHandshakeException) { 
// 不 要 重 试 SSL 握 手 异 常 
return false; 


} 
HttpRequest request = (HttpRequest) context.getAttribute 


ExecutionContext .HTTP_REQUEST ) ; 
boolean idempotent = !(request instanceof HttpEntityEncl 
osingRequest ); 
if (idempotent) { 
// oR RBRVA LRN > BARE IK 
return true; 


return false; 


} 
}; 
httpclient.setHttpRequestRetryHandler (myRetryHandler); 


1.4 中 止 请 求 


在 一 些 情况 下 ， 由 于 目标 服务 器 的 高 负载 或 客户 端 有 很 多 活动 的 请 求 ， 那 么 HTTP 
请 求 执行 会 在 预期 的 时 间 框 内 而 失败 。 这 时 ， 就 可 能 不 得 不 过 早 地 中 止 请 求 ， 解 除 
封锁 在 /DO 执 行 中 的 线程 封锁 。 被 HttpClient 执 行 的 HTTP 请 求 可 以 在 执行 的 任意 阶段 
通过 调用 HttpUriRequest#abort() 方 法 而 中 止 。 这 个 方法 是 线程 实 全 的 ， 而 且 可 以 从 
任意 线程 中 调用 。 当 一 个 HTTP 请 求 被 中 止 时 ， 它 的 执行 线程 就 封锁 在 |/O 操 作 中 

了 ， 而 且 保 证 通过 抛 出 InterruptedlOException 蜡 常 来 解锁 。 


1.5 HTTP 协 议 拦截 器 


HTTP 协 议 拦截 器 是 一 个 实现 了 特定 HTPP 协 议 方面 的 惯例 。 通 常 协议 拦截 器 希望 作 
用 于 一 个 特定 头 部 信息 上 ， 或 者 一 族 收 到 报 文 的 相关 头 部 信息 ， 或 使 用 一 个 特定 的 
头 部 或 一 族 相 关 的 头 部 信息 填充 发 出 的 报 文 。 协 议 拦 截 器 也 可 以 操纵 包含 在 报 文中 


的 内 容 实 体 ， 透 明 的 内 容 压 缩 /解压 就 是 一 个 很 好 的 示例 。 通 常情 况 下 这 是 由 包装 器 
实体 类 使 用 了 “装饰 者 "模式 来 装饰 原始 的 实体 完成 的 。 一 些 协议 拦截 器 可 以 从 一 个 
逻辑 单元 中 来 结合 。 


协议 拦截 器 也 可 以 通过 共享 信息 来 共同 合作 -比如 处 理 状态 -通过 HTTP 执 行 上 下 文 。 
协议 拦截 器 可 以 使 用 HTTP 内 容 来 为 一 个 或 多 个 连续 的 请 求 存储 一 个 处 理 状态 。 


通常 拦截 器 执行 的 顺序 不 应 该 和 它们 基于 的 特定 执行 上 下 文 状态 有 关 。 如 果 协 议 搓 
截 器 有 相互 依存 关系 ， 那 么 它们 必须 按 特定 顺序 来 执行 ， 正 如 它们 希望 执行 的 顺序 
一 样 ， 它 们 应 该 在 相同 的 序列 中 被 加 到 协议 处 理 器 。 


协议 拦截 器 必须 实现 为 线程 安全 的 。 和 Servlet 相 似 ， 协 议 拦 截 器 不 应 该 使 用 实例 变 
量 ， 除 非 访 问 的 那些 变量 是 同步 的 。 


这 个 示例 给 出 了 本 地 内 容 在 连续 的 请 求 中 怎么 被 用 于 持久 一 个 处 理 状 态 的 : 


DefaultHttpClient httpclient = new DefaultHttpClient(); 
HttpContext localContext = new BasicHttpContext(); 
AtomicInteger count = new AtomicInteger(1); 
localContext.setAttribute("count", count); 
httpclient.addRequestInterceptor(new HttpRequestInterceptor() { 
public void process(final HttpRequest request, 
final HttpContext context) throws HttpException, IOException 


{ 
AtomicInteger count = (AtomicInteger) context.getAttribu 


te("count"); 
request.addHeader("Count", Integer.toString(count.getAnd 
Increment())); 


}); 
HttpGet httpget = new HttpGet("http://localhost/"); 


for (int i = 0; i < 10; i++) { 
HttpResponse response = httpclient.execute(httpget, localCon 
text); 
HttpEntity entity = response.getEntity(); 
if (entity != null) { 
entity.consumeContent(); 


} 


1.6 HTTP #2 


HttpParams 接 口 代 表 了 定义 组 件 运行 时 行为 的 一 个 不 变 的 值 的 集合 。 很 多 情况 下 ， 
HttpParams 和 HttpContext 相 似 。 二 者 之 间 的 主要 区 别 是 它们 在 运行 时 使 用 的 不 

同 。 这 两 个 接口 表示 了 对 象 的 集合 ， 它 们 被 视 作 为 访问 对 象 值 的 键 的 Map， 但 是 服 
务 于 不 同 的 目的 : 


e HttpParams 旨 在 包含 简单 对 象 : 整 型 ， 浮 点 型 ， 字 符 串 ， 集 合 ， 还 有 运行 时 不 
变 的 对 象 。 


e HttpParams 和 希望 被 用 在 “一 次 写 入 -多 处 准备 "模式 下 。HttpContext 旨 在 包含 很 
可 能 在 HTTP 报 文 处理 这 一 过 程 中 发 生 改 变 的 复杂 对 象 

e HttpParams 的 目标 是 定义 其 它 组 件 的 行为 。 通 常 每 一 个 复杂 的 组 件 都 有 它 自 
的 HttpParams 对 象 。HttpContext 的 目标 是 来 表示 一 个 HTTP 处 理 的 执行 状态 
通常 相同 的 执行 上 下 文 在 很 多 合作 的 对 象 中 共享 。 


已 


1.6.1 参数 层次 


在 HTTP 请 求 执行 过 程 中 ，HttpRequest 对 象 的 HttpParams 是 和 用 于 执行 请 求 的 
HttpClient 实 例 的 HttpParams 联 系 在 一 起 的 。 这 使 得 设置 在 HTTP 请 求 级 别 的 参数 优 
先 于 设置 在 HTTP 客 户 端 级 别 的 HttpParams。 推 荐 的 做 法 是 设置 普通 参数 对 所 有 的 
在 HTTP 客 户 端 级 别 的 HTTP 请 求 共享 ， 而 且 可 以 选择 性 重 写 具体 在 HTTP 请 求 级 别 
的 参数 。 


DefaultHttpClient httpclient = new DefaultHttpClient(); 
httpclient.getParams().setParameter(CoreProtocolPNames .PROTOCOL _ 
VERSION, HttpVersion.HTTP_1_0); 
httpclient.getParams().setParameter(CoreProtocolPNames.HTTP_CONT 
ENT_CHARSET, "UTF-8"); 
HttpGet httpget = new HttpGet("http://www.google.com/"); 
httpget.getParams().setParameter(CoreProtocolPNames.PROTOCOL_VER 
SION, HttpVersion.HTTP_1_1); 
httpget.getParams().setParameter(CoreProtocolPNames.USE_EXPECT_C 
ONTINUE, Boolean. FALSE); 
httpclient.addRequestInterceptor(new HttpRequestInterceptor() { 
public void process(final HttpRequest request, 
final HttpContext context) throws HttpException, IOExcep 


tion { 
System.out.println(request.getParams().getParameter ( 
CoreProtocolPNames.PROTOCOL_VERSION) ); 
System.out.println(request.getParams().getParameter ( 
CoreProtocolPNames.HTTP_CONTENT_CHARSET ) ); 
System.out.println(request.getParams().getParameter ( 
CoreProtocolPNames.USE_EXPECT_CONTINUE) ); 
System.out.println(request.getParams().getParameter ( 
CoreProtocolPNames.STRICT_TRANSFER_ENCODING) ); 
} 
}); 
输出 内 容 为 : 
HTTP/1.1 
UTF-8 
false 
null 


1.6.2 HTTP #& 2bean 


HttpParams 接 只 允许 在 处 理 组 件 的 配置 上 很 大 的 灵活 性 。 很 重要 的 是 ， 新 的 参数 可 
以 被 引入 而 不 会 影响 老 版 本 的 二 进 制 兼容 性 。 然 而 ， 和 常规 的 Java bean 相 比 ， 
HttpParams 也 有 一 个 缺点 : HttpParams 不 能 使 用 DI 框架 来 组 合 。 为 了 缓解 这 个 限 
制 ，HttpClient 包 含 了 一 些 bean 类 ， 它 们 可 以 用 来 按 顺 序 使 用 标准 的 Java eban 惯 例 
初始 化 HttpParams 对 象 。 


HttpParams params = new BasicHttpParams(); 
HttpProtocolParamBean paramsBean = new HttpProtocolParamBean(par 
ams); 
paramsBean.setVersion(HttpVersion.HTTP_1 1); 
paramsBean.setContentCharset("UTF-8"); 
paramsBean. setUseExpectContinue(true) ; 
System.out.printiln(params.getParameter ( 
CoreProtocolPNames.PROTOCOL_VERSION) ); 
System.out.println(params.getParameter ( 
CoreProtocolPNames.HTTP_CONTENT_CHARSET ) ); 
System.out.println(params.getParameter ( 
CoreProtocolPNames.USE_EXPECT_CONTINUE) ); 
System.out.println(params.getParameter ( 
CoreProtocolPNames.USER_AGENT) ); 


输出 内 容 为 : 


HTTP/1.1 
UTF-8 
false 
null 


1.7 HTTP 请 求 执 行 参 数 


这 些 参数 会 影响 到 请 求 执 行 的 过 程 : 


e http.protocol.version : 如 果 没 有 在 请 求 对 象 中 设置 明确 的 版 本 信息 ， 它 
就 定义 了 使 用 的 HTTP 协 议 版 本 。 这 个 参数 期 望 得 到 一 个 ProtocolVersion 类 型 
的 值 。 如 果 这 个 参数 没有 被 设置 ， 那 么 就 使 用 HTTP/1.1 © 

e http.protocol.element-charset :定义 了 编码 HTTP 协 议 元 素 的 字符 集 。 
这 个 参数 期 望 得 到 一 个 java.lang.String 类 型 的 值 。 如 果 这 个 参数 没有 被 设置 ， 
那么 就 使 用 US-ASCII。 

e http.protocol.eontent-charset :定义 了 为 每 个 内 容 主体 编码 的 默认 字 
符 集 。 这 个 参数 期 望 得 到 一 个 java.lang.String 类 型 的 值 。 如 果 这 个 参数 没有 被 
设置 ， 那 么 就 使 用 ISO-8859-1。 

e http.useragent : 定义 了 头 部 信息 User-Agent 的 内 容 。 这 个 参数 期 望 得 到 
一 个 java.lang.String 类 型 的 值 。 如 果 这 个 参数 没有 被 设置 ， 那 么 HttpClient 将 会 
为 它 自动 生成 一 个 值 。 

e http.protocol.strict-transfer-encoding : 定义 了 响应 头 部 信息 中 是 否 
含有 一 个 非法 的 Transfer-Encoding， 都 要 拒绝 掉 。 


http.protocol.expect-continue :为 包含 方法 的 实体 激活 Expect: 100- 
Continue 握 手 。Expect: 100-Continue 担 手 的 目的 是 允许 客户 端 使 用 请 求 体 发 
送 一 个 请 求 信息 EPA RENE E ey 端 发 送 请 求 体 之 前 得 到 这 个 请 
R (基于 请 求 头 部 信息 ) © Expect: 100-Continue 握 手 的 使 用 可 以 对 需要 目标 
服务 器 认证 的 包含 请 求 的 实体 (比如 POST 和 PUT) 导致 明显 的 性 能 改善 。 
Expect: 100-Continue 担 手 应 该 谨 民 使用， 因为 As eg 器 ， 不 支持 
HTTP/1. WS E es 。 这 个 参数 期 望 得 到 一 
java.lang.Boolean 类 型 的 值 。 如 果 这 个 参数 没有 被 设置 ， 那 么 区 试 
图 使 用 握手 。 

http.protocol.wait-for-continue : 定义 了 客户 端 应 该 等 待 100- 
Continue 响 应 最 大 的 毫秒 级 时 间 间 隔 。 这 个 参数 期 望 得 到 一 个 java.lang.Integer 
类 型 的 值 。 如 果 这 个 参数 没有 被 设置 ， 那 么 EA 会 在 恢复 请 求 体 传输 之 
前 为 确认 等 待 3 秒 。 


大 大 


Aa 


二 章 连接 管理 


HttpClient 有 一 个 对 连接 初始 化 和 终止 ， 还 有 在 活动 连接 上 IO 操作 的 完整 控制 。 而 
连接 操作 的 很 多 方面 可 以 使 用 一 些 参数 来 控制 。 


2.1 连接 参数 


这 些 参数 可 以 影响 连接 操作 : 


http.socket.timeout :定义 了 和 套 接 字 的 毫秒 级 超时 时 间 

(SO_TIMEOUT) ， 这 就 是 等 待 数据 ， 换 名 话说 ， 在 两 个 连续 的 数据 包 之 间 
最 大 的 闲置 时 间 。 如 果 超 时 时 间 是 0 就 解释 为 是 一 个 无 限 大 的 超时 时 间 。 这 个 
参数 期 望 得 到 一 个 java.lang.Integer 类 型 的 值 。 如 果 这 个 参数 没有 被 设置 ， 那 么 
读 取 操作 就 不 会 超时 (无 限 大 的 超时 时 间 ) 。 

http.tcp.nodelay : 决定 了 是 否 使 用 Nagle 算 法 。Nagle 算 法 视图 通过 最 小 
化 发 送 的 分 组 数量 来 节省 带宽 。 当 应 用 程序 希望 降低 网 络 延迟 并 提高 性 能 时 ， 
它们 可 以 关闭 Nagle 算 法 (也 就 是 开启 TCP_NODELAY) 。 数 据 将 会 更 早 发 
送 ， 增 加 了 带宽 消耗 的 成 文 。 这 个 参数 期 望 得 到 一 个 java.lang.Boolean 类 型 的 
值 。 如 果 这 个 参数 没有 被 设置 ， 那 么 TCP_NODELAY 就 会 开启 (AER) © 
http.socket.buffer-size : 决定 了 内 部 套 接 字 缓冲 使 用 的 大 小 ， 来 缓冲 数 
据 同 时 接收 /传输 HTTP 报 文 。 这 个 参数 期 望 得 到 一 个 java.lang.Integer 类 型 的 
值 。 如 果 这 个 参数 没有 被 设置 ， 那 么 HttpClient 将 会 分 配 8192 字 节 的 套 接 字 缓 
pa 

http.socket.linger :使 用 指定 的 秒 数 拖 延 时 间 来 设置 SO_LINGER。 有 最 大 
的 连接 超时 值 是 平台 指定 的 。 值 0 暗示 了 这 个 选项 是 关闭 的 。 值 -1 暗示 了 使 用 
了 JRE 默 认 的 。 这 个 设置 仅仅 影响 套 接 字 关 闭 操作 。 如 果 这 个 参数 没有 被 设 

置 ， 那 么 就 假设 值 为 -1 (JRE 上 默认 ) 。 

http.connection.timeout :决定 了 直到 连接 建立 时 的 毫秒 级 超时 时 间 。 超 
时 时 间 的 值 为 0 解释 为 一 个 无 限 大 的 时 间 。 这 个 参数 期 望 得 到 一 个 
java.lang.Integer 类 型 的 值 。 如 果 这 个 参数 没有 被 设置 ， 连 接 操作 将 不 会 超时 

(无 限 大 的 超时 时 间 ) o 

http.connection.stalecheck : 决定 了 是 否 使 用 昌 的 连接 检查 。 当 在 一 个 
连接 之 上 执行 一 个 请 求 而 服务 器 端的 连接 已 经 关闭 时 ， 关 闭 昌 的 连接 检查 可 能 
导致 在 获得 一 个 /0 错误 风险 时 显著 的 性 能 提升 (对 于 每 一 个 请 求 ， 检 查 时 间 可 
以 达到 30 毫 秒 ) 。 这 个 参数 期 望 得 到 一 个 java.lang.Boolean 类 型 的 值 。 出 于 性 
能 的 关键 操作 ， 检 查 应 该 被 关闭 。 如 果 这 个 参数 没有 被 设置 ， 那 么 加 的 连接 将 
会 在 每 个 请 求 执 行 之 前 执行 。 

http.connection.max-line-length : 决定 了 最 大 请 求 行 长 度 的 限制 。 如 
果 设 置 为 一 个 正 数 ， 任 何 HTTP 请 求 行 超过 这 个 限制 将 会 引发 
java.io.IOException 蜡 常 。 负 数 或 零 将 会 关闭 这 个 检查 。 这 个 参数 期 望 得 到 一 
个 java.lang.Integer 类 型 的 值 。 如 果 这 个 参数 没有 被 设置 ， 那 么 就 不 强制 进行 限 
制 了 。 

http.connection.max-header-count : 决定 了 允许 的 最 大 HTTP 头 部 信息 
数量 。 如 果 设 置 为 一 个 正 数 ， 从 数据 流 中 获得 的 HTTP 头 部 信息 数量 超过 这 个 


限制 就 会 引发 ava.io.IOException 异 常 。 负 数 或 零 将 会 关闭 这 个 检查 。 这 个 参 
数 期 望 得 到 一 个 java.lang.Integer 类 型 的 值 。 如 果 这 个 参数 没有 被 设置 ， 那 么 就 
不 

o 强制 进行 限制 了 。 

e http.connection.max-status-line-garbage : 决定 了 在 期 望 得 到 HTTP 
响应 状态 行 之 前 可 忽略 请 求 行 的 最 大 数量 。 使 用 HTTP/1.1 持 久 性 连接 ， 这 个 问 
题 产 生 的 破碎 的 脚本 将 会 返回 一 个 错误 的 Content-Length (有 比 指定 的 字 节 更 
多 的 发 送 ) 。 不 幸 的 是 ， 在 某 些 情况 下 ， 这 个 不 能 在 错误 响应 后 来 侦 测 ， 只 能 
在 下 一 次 之 前 。 所 以 HttpClient 必 须 以 这 种 方式 跳 过 那些 多 余 的 行 。 这 个 参数 期 
望 得 到 一 个 java.lang.Integer 类 型 的 值 。0 是 不 允许 在 状态 行 之 前 的 所 有 垃圾 / 空 
行 。 使 用 java.lang.Integer#MAX_VALUE 来 设置 不 限制 的 数字 。 如 果 这 个 参数 
没有 被 设置 那 就 假设 是 不 限制 的 。 


2.2 持久 连接 


从 一 个 主机 向 另外 一 个 建立 连接 的 过 程 是 相当 复杂 的 ， 而 且 包 含 了 两 个 终端 之 间 的 
很 多 包 的 交换 ， 它 是 相当 费时 的 。 连 接 握 手 的 开销 是 很 重要 的 ， 特 别 是 对 小 量 的 
HTTP 报 文 。 如 果 打 开 的 连接 可 以 被 重用 来 执行 多 次 请 求 ， 那 么 就 可 以 达到 很 高 的 
RUBLE © 


HTTP/1.1 强 调 HTTP 连 接 默认 情况 可 以 被 重用 于 多 次 请 求 。HTTP/1.0 兼 容 的 终端 也 
可 以 使 用 相似 的 机 制 来 明确 地 交流 它们 的 偏好 来 保证 连接 处 于 活动 状态 ， 也 使 用 它 
来 处 理 多 个 请 求 。HTTP 代 理 也 可 以 保持 空闲 连接 处 于 一 段 时 间 的 活动 状态 ， 防 止 
对 相同 目标 主机 的 一 个 连接 也 许 对 随后 的 请 求 需 要 。 保 持 连 接 活动 的 能 力 通 常 被 称 
作 持 久 性 连接 。HttpClient 完 全 支持 持久 性 连接 。 


2.3 HTTP 连 接 路 由 


HttpClient 能 够 直接 或 通过 路 由 建立 连接 到 目标 主机 ， 这 会 涉及 多 个 中 间 连 接 ， 也 被 
称 为 跳 。HttpClient 区 分 路 由 和 普通 连接 ， 通 道 和 分 层 。 通 道 连接 到 目标 主机 的 多 个 
中 间 代 理 的 使 用 也 称 作 是 代理 链 。 


普通 路 由 由 连接 到 目标 或 仅 第 一 次 的 代理 来 创建 。 通 道路 由 通过 代理 链 到 目标 连接 
到 第 一 通道 来 建立 。 没 有 代理 的 路 由 不 是 通道 的 ， 分 层 路 由 通过 已 存在 连接 的 分 层 
协议 来 建立 。 协 议 仅 仅 可 以 在 到 目标 的 通道 上 或 在 没有 代理 的 直接 连接 上 分 层 。 


2.3.1 路 由 计算 


Routelnfo 接 口 代表 关于 最 终 涉 及 一 个 或 多 个 中 间 步 骤 或 跳 的 目标 主机 路 由 的 信息 。 
HttpRoute 是 Routelnfo 的 具体 实现 ， 这 是 不 能 改变 的 〈 是 不 变 的 ) 。HttpTracker 是 
可 变 的 Routelnfo 实 现 ， 由 HttpClient 在 内 部 使 用 来 跟踪 到 最 大 路 由 目标 的 剩余 跳 
数 。HttpTracker 可 以 在 成 功 执行 向 路 由 目标 的 下 一 跳 之 后 更 新 。HttpRouteDirector 
是 一 个 帮助 类 ， 可 以 用 来 计算 路 由 中 的 下 一 跳 。 这 个 类 由 HttpClient 在 内 部 使 用 。 


HttpRoutePlanner 是 一 个 代表 计算 到 基于 执行 上 下 文 到 给 定 目标 完整 路 由 策略 的 接 
口 。HttpClient 附 带 两 个 默认 的 HttpRoutePlanner 实 现 。 
ProxySelectorRoutePlanner 是 基于 java.net.ProxySelector 的 。 上 默认 情况 下 ， 它 会 从 
系统 属性 中 或 从 运行 应 用 程序 的 浏览 器 中 选取 JVM 的 代理 设置 。 
DefaultHttpRoutePlanner 实 现 既 不 使 用 任何 Java 系 统 属性 ， 也 不 使 用 系统 或 浏览 器 
的 代理 设置 。 它 只 基于 HTTP 如 下 面 描述 的 参数 计算 路 由 。 


2.3.2 安全 HTTP 连 接 


如 果 信 息 在 两 个 不 能 由 非 认 证 的 第 三 方 进行 读 取 或 修改 的 终端 之 间 传 输 ，HTTP 连 
接 可 以 被 认为 是 安全 的 。SSL/TLS 协 议 是 用 来 保证 HTTP 传 输 安全 使 用 最 广泛 的 技 
术 。 而 其 它 加 密 技 术 也 可 以 被 使 用 。 通 常 来 说 ，HTTP 传 输 是 在 SSL/TLS 加 密 连 接 
之 上 分 层 的 。 


2.4 HTTP 路 由 参数 


这 些 参 数 可 以 影响 路 由 计算 . 


e http.route.default-proxy : 定义 可 以 被 不 使 用 JRE 设 置 的 默认 路 由 规划 
者 使 用 的 代理 主机 。 这 个 参数 期 望 得 到 一 个 HttpHost 类 型 的 值 。 如 果 这 个 参数 
没有 被 设置 ， 那 么 就 会 尝试 直接 连接 到 目标 。 

e http.route.local-address : 定义 一 个 本 地 地 址 由 所 有 默认 路 由 规划 者 来 
使 用 。 有 多 个 网 络 接 口 的 机 器 中 ， 这 个 参数 可 以 被 用 于 从 连接 源 中 选择 网 络 接 
口 。 这 个 参数 期 望 得 到 一 个 java.net.InetAddress 类 型 的 值 。 如 果 这 个 参数 没有 
被 设置 ， 将 会 自动 使 用 本 地 地 址 。 

e http.route.forced-route :定义 一 个 由 所 有 默认 路 由 规划 者 使 用 的 强制 路 
由 。 代 替 了 计算 路 由 ， 给 定 的 强制 路 由 将 会 被 返回 ， 尽 管 它 指 向 一 个 完全 不 同 
的 目标 主机 。 这 个 参数 期 望 得 到 一 个 HttpRoute 类 型 的 值 。 如 果 这 个 参数 没有 
被 设置 ， 那 么 就 使 用 默认 的 规则 建立 连接 到 目标 服务 器 。 


2.5 BFL 


LayeredSocketFactory 是 SocketFactory 接 口 的 扩展 。 分 层 的 套 接 字 工 厂 可 HTTP 连 
接 内 部 使 用 java.net.Socket 对 象 来 处 理 数据 在 线路 上 的 传输 。 它 们 依赖 
SocketFactory 接 口 来 创建 ， 初 始 化 和 连接 套 接 字 。 这 会 使 得 HttpClient 的 用 户 可 以 
提供 在 运行 时 指定 套 接 字 初 始 化 代码 的 应 用 程序 。PlainSocketFactory 是 创建 和 初 
始 化 普通 的 (不 加 密 的 ) 套 接 字 的 默认 工厂 。 


创建 套 接 字 的 过 程 和 连接 到 主机 的 过 程 是 不 成 对 的 ， 所 以 套 接 字 在 连接 操作 封锁 时 
可 以 被 关闭 。 


PlainSocketFactory sf = PlainSocketFactory.getSocketFactory(); 
Socket socket = sf.createSocket(); 

HttpParams params = new BasicHttpParams(); 
params.setParameter(CoreConnectionPNames.CONNECTION_TIMEOUT, 100 
OL); 

sf.connectSocket(socket, "locahost", 8080, null, -1, params); 


2.5.1 安全 套 接 字 分 层 


LayeredSocketFactory 是 SocketFactory 接 口 的 扩展 。 分 层 的 套 接 字 工 厂 可 以 创建 在 
已 经 存在 的 普通 套 接 字 之 上 的 分 层 套 接 字 。 套 接 字 分 层 主要 通过 代理 来 创建 安全 的 
套 接 字 。HttpClient 附 带 实 现 了 SSL/TLS 分 层 的 SSLSocketFactory。 请 注意 
HttpClient 不 使 用 任何 自 定 义 加 密 功 能 。 它 完全 依赖 于 标准 的 Java 密 码 学 (JCE) 和 
安全 套 接 字 (JSEE) 扩展 。 


2.5.2 SSL/TLS 的 定制 


HttpClient 使 用 SSLSocketFactory 来 创建 SSL 连 接 。SSLSocketFactory 允 许 高 度 定 
制 。 它 可 以 使 用 javax.net.ssl.SSLContext 的 实例 作为 参数 ， 并 使 用 它 来 创建 定制 
SSL 连 接 。 


TrustManager easyTrustManager = new X509TrustManager() { 
@Override 
public void checkClientTrusted(X509Certificate[] chain, 
String authType) throws CertificateException { 
// 哦 ， 这 很 简单 ! 
} 
@Override 
public void checkServerTrusted(X509Certificate[] chain, 
String authType) throws CertificateException { 
// 哦 ， 这 很 简单 ! 
} 
@Override 
public X509Certificate[] getAcceptedIssuers() { 
return null; 
} 
J; 


SSLContext sslcontext = SSLContext.getInstance("TLS"); 
sslcontext.init(null, new TrustManager[] { easyTrustManager }, n 
ull); 

SSLSocketFactory sf = new SSLSocketFactory(sslcontext); 
SSLSocket socket = (SSLSocket) sf.createSocket(); 
socket.setEnabledCipherSuites(new String[] { "SSL_RSA_WITH_RC4_1 
28_MD5" }); 

HttpParams params = new BasicHttpParams(); 

params.setParameter (CoreConnectionPNames.CONNECTION_TIMEOUT, 100 
OL); 

sf.connectSocket(socket, "locahost", 443, null, -1, params); 





SSLSocketFactory 的 定制 暗示 出 一 定 程度 SSL/TLS 协 议 概 念 的 熟悉 ， 这 个 详细 的 解 
释 超 出 了 本 文档 的 范围 。 请 参考 Java 的 安全 套 接 字 扩展 ， 这 是 
javax.net.ssl.SSLContext 和 相关 工具 的 详细 描述 。 


2.5.3 主机 名 验证 


除了 信任 验证 和 客户 端 认证 在 SSL/TLS 协 议 级 上 进行 ， 一 旦 连接 建立 之 后 ， 
HttpClient 能 可 选 地 验证 目标 主机 名 匹配 存储 在 服务 器 的 X.509 认 证 中 的 名 字 。 这 个 
认证 可 以 提供 额外 的 服务 器 信任 材料 的 丨 实 保证 。X509 主 机 名 验证 接口 代表 了 主机 
名 验证 的 策略 。HttpClient 附 带 了 3 个 X509 主 机 名 验证 器 。 很 重要 的 一 点 是 : 主机 名 
验证 不 应 该 混淆 SSL 信 任 验证 。 


e StrictHostnameVerifier : 严格 的 主机 名 验证 在 Sun Java 1.4，Sun Java 5 和 
Sun Java 6 中 是 相同 的 。 而 且 也 非常 接近 IE6。 这 个 实现 似乎 是 兼容 RFC 2818 
处 理 通配符 的 。 主 机 名 必须 匹配 第 一 个 CN 或 任意 的 subject-alt。 在 CN 和 其 它 
任意 的 subject-alt 中 可 能 会 出 现 通配符 。 

e BrowserCompatHostnameVerifier : 主机 名 验证 器 和 Curl 和 Firefox 的 工作 方式 
是 相同 的 。 主 机 名 必须 匹配 第 一 个 CN 或 任意 的 subject-alt。 在 CN 和 其 它 任 意 
的 subject-alt 中 可 能 会 出 现 通配符 。BrowserCompatHostnameVerifier 和 
StrictHostnameVerifier 的 唯一 不 同 是 使 用 BrowserCompatHostnameVerifier 匹 
配 所 有 子 域 的 通配符 (比如 ”*,foo.com”) > &4&”a.b.foo.com” ° 


e AllowAllHostnameVerifier : 这 个 主机 名 验证 器 基本 上 是 关闭 主机 名 验 = ay o 3X 
SKIL ERNE > HAA SH Wjavax.net.ssl.SSLException+ # 


每 一 个 默认 的 HttpClient 使 用 BrowserCompatHostnameVerifier 的 实现 。 如 果 需 要 的 
话 ， 它 可 以 指定 不 同 的 主机 名 验证 器 实现 。 


SSLSocketFactory sf = new SSLSocketFactory(SSLContext.getInstanc 
aS ie 

sf.setHostnameVerifier (SSLSocketFactory.STRICT_HOSTNAME_ VERIFIER 
); 


2.6 协议 模式 


Scheme 类 代表 了 一 个 协议 模式 ， 比 如 “http" 或 “https" 同 时 包含 一 些 协 议 属性 ， 比 如 
默认 端口 ， 用 来 为 给 定 协 议 创建 java.net. So | 的 aed o 
R nm. anu ， 当 去 通过 请 求 URI 建 立 连接 时 ， 
HttpClient 可 以 从 中 选 


Scheme http = new Scheme("http", PlainSocketFactory.getSocketFac 
tory(), 80); 

SSLSocketFactory sf = new SSLSocketFactory(SSLContext.getInstanc 
e("TLS")); 

sf.setHostnameVerifier (SSLSocketFactory.STRICT_HOSTNAME VERIFIER 
); 

Scheme https = new Scheme("https", sf, 443); 

SchemeRegistry sr = new SchemeRegistry(); 

sr.register(http); 

sr.register(https); 


2.7 HttpClient 代 理 配 置 


尽管 HttpClient 了 解 复杂 的 路 由 模式 和 代理 链 ， 它 仅 支持 简单 直接 的 或 开 箱 的 跳 式 代 
理 连接 。 


告诉 HttpClient 通 过 代理 去 连接 到 目标 主机 的 最 简单 方式 是 通过 设置 默认 的 代理 参 
数 : 


DefaultHttpClient httpclient = new DefaultHttpClient(); 

HttpHost proxy = new HttpHost("someproxy", 8080); 
httpclient.getParams().setParameter(ConnRoutePNames .DEFAULT_PROX 
Y, proxy); 


也 可 以 构建 HttpClient 使 用 标准 的 JRE 代 理 选择 器 来 获得 代理 信息 : 


DefaultHttpClient httpclient = new DefaultHttpClient(); 
ProxySelectorRoutePlanner routePlanner = new ProxySelectorRouteP 
lanner( 
httpclient.getConnectionManager().getSchemeRegistry(), 
ProxySelector.getDefault()); 
httpclient.setRoutePlanner(routePlanner ) ; 


另外 一 种 选择 ， 可 以 提供 一 个 定制 的 RoutePlanner 实 现 来 获得 HTTP 路 由 计算 处 理 
上 的 复杂 的 控制 : 


DefaultHttpClient httpclient = new DefaultHttpClient(); 
httpclient.setRoutePlanner(new HttpRoutePlanner() { 
public HttpRoute determineRoute(HttpHost target, 
HttpRequest request, 
HttpContext context) throws HttpException { 
return new HttpRoute(target, null, new HttpHost("somepro 
xy", 8080), 


} 


"https".equalsIgnoreCase(target.getSchemeName())); 


}); 


2.8 HTTP 连 接管 理 器 


2.8.1 连接 操作 器 


连接 操作 是 客户 端的 低层 套 接 字 或 可 以 通过 外 部 实体 ， 通 常 称 为 连接 操作 的 被 操作 
的 状态 的 连接 。OperatedClientConnection 接 口 扩 展 了 HttpClientConnection 接 口 而 
且 定 义 了 额外 的 控制 连接 套 接 字 的 方法 。ClientConnectionOperator 接 口 代表 了 创 
建 实例 和 更 新 那些 对 象 低 层 套 接 字 的 策略 。 实 现 类 最 有 可 能 利用 SocketFactory 来 创 
建 java.net.Socket 实 例 。ClientConnectionOperator 接 口 可 以 让 HttpClient 的 用 户 提 
供 一 个 连接 操作 的 定制 策略 和 提供 可 选 实现 OperatedClientConnection 接 口 的 能 

力 。 


2.8.2 管理 连接 和 连接 管理 器 


HTTP 连 接 是 复杂 的 ， 有 状态 的 ， 线 程 不 安全 的 对 象 需要 正确 的 管理 以 便 正 确 地 执 
行 功能 。HTTP 连 接 在 同一 时 间 仅 仅 只 能 由 一 个 执行 线程 来 使 用 。HttpClient 采 用 一 
个 特殊 实体 来 管理 访问 HTTP 连 接 ， 这 被 称 为 HTTP 连 接管 理 器 ， 代 表 了 
ClientConnectionManager 接 口 。 一 个 HTTP 连 接管 理 器 的 目的 是 作为 工厂 服务 于 新 
的 HTTP 连 接 ， 管 理 持久 连接 和 同步 访问 持久 连接 来 确保 同一 时 间 仅 有 一 个 线程 可 
以 访问 一 个 连接 。 


内 部 的 HTTP 连 接管 理 器 和 OperatedClientConnection 实 例 一 起 工作 ， 但 是 它们 为 服 
务 消耗 器 ManagedClientConnection 提 供 实例 。ManagedClientConnection 扮 演 连 
接 之 上 管理 状态 控制 所 有 I/O 操 作 的 OperatedClientConnection 实 例 的 包装 器 。 它 也 


抽象 套 接 字 操 作 ， 提 供 打 开 和 更 新 去 创建 路 由 套 接 字 便 利 的 方法 。 
ManagedClientConnection 实 例 了 解 产生 它们 到 连接 管理 器 的 链接 ， 而 且 基于 这 个 
事实 ， 当 不 再 被 使 用 时 ， 它 们 必须 返回 到 管理 器 。ManagedClientConnection 类 也 
实现 了 ConnectionReleaseTrigger 接 口 ， 可 以 被 用 来 触 发 释放 和 连接 返回 给 管理 器 器 。 
一 旦 释放 连接 操作 被 触发 了 ， 被 包装 BY M ManagedClientConnection 包装 器 中 
脱离 ，OperatedClientConnection 实 例 被 返回 给 管理 器 。 尺 管 服务 消耗 器 仍 然 持 有 
ManagedClientConnection 实 例 的 引用 ， 它 也 不 再 去 执行 任何 JJO 操 作 或 有 意 无 意 地 
改变 的 OperatedClientConnection 状 态 。 


这 里 有 一 个 从 连接 管理 器 中 获取 连接 的 示例 : 


HttpParams params = new BasicHttpParams(); 
Scheme http = new Scheme("http", PlainSocketFactory.getSocketFac 
tory(), 80); 
SchemeRegistry sr = new SchemeRegistry(); 
sr.register(http); 
ClientConnectionManager connMrg = new SingleClientConnManager(pa 
rams, sr); 
// 请 求 新 连接 。 这 可 能 是 一 个 很 长 的 过 程 。 
ClientConnectionRequest connRequest = connMrg.requestConnection( 
new HttpRoute(new HttpHost("localhost", 80)), null); 
// 等 待 连接 10 秒 
ManagedClientConnection conn = connRequest.getConnection(10, Tim 
eUnit.SECONDS); 
try { 
// 用 连接 在 做 有 用 的 事情 。 当 完成 时 释放 连接 。 
conn.releaseConnection(); 
} catch (IOException ex) { 
// 在 I/0 error 之 上 终止 连接 。 
conn.abortConnection(); 
throw ex; 


如 果 需 要 ， 连 接 请 求 可 以 通过 调用 来 ClientConnectionRequest#abortRequest() 方 
ALP HL YP BH o K AMAT ClientConnectionRequest#getConnection() 7% = P 3k ME. 
止 的 线程 。 


一 旦 响应 内 容 被 完全 消耗 后 ，BasicManagedEntity 包 装 器 类 可 以 用 来 保证 自动 释放 
低层 的 连接 。HttpClient 内 部 使 用 这 个 机 制 来 实现 透明 地 对 所 有 从 
HttpClient#execute() 方 法 中 获得 响应 释放 连接 : 


ClientConnectionRequest connRequest = connMrg.requestConnection( 

new HttpRoute(new HttpHost("localhost", 80)), null); 
ManagedClientConnection conn = connRequest.getConnection(10, Tim 
eUnit.SECONDS); 


try { 
BasicHttpRequest request = new BasicHttpRequest("GET", "/"); 
conn.sendRequestHeader (request); 
HttpResponse response = conn.receiveResponseHeader(); 
conn.receiveResponseEntity(response) ; 
HttpEntity entity = response.getEntity(); 
if (entity != null) { 
BasicManagedEntity managedEntity = new BasicManagedEntit 
y(entity, conn, true); 
// 替换 实体 
response.setEntity(managedEntity); 


} 

// 使 用 响应 对 象 做 有 用 的 事情 。 当 响应 内 容 被 消耗 后 这 个 连接 将 会 自动 释放 。 
} catch (IOException ex) { 

// 在 I/0 error 之 上 终止 连接 。 

conn.abortConnection(); 

throw ex; 


2.8.3 简单 连接 管理 器 


SingleClientConnManager 有 是 一 个 简单 的 连接 管理 器 ， 在 同一 时 间 它 仅仅 维护 一 个 
连接 。 尽 管 这 个 类 是 线程 安全 的 ， 但 它 应 该 被 用 于 一 个 执行 线程 。 
SingleClientConnManager 对 于 同一 路 由 的 后 续 请 求 会 尽量 重用 连接 。 而 如 果 持 久 
连接 的 路 由 不 匹配 连接 请 求 的 话 ， 它 也 会 关闭 存在 的 连接 之 后 对 给 定 路 由 再 打开 一 
个 新 的 。 如 果 连 接 已 经 被 分 配 ， 将 会 抛 出 java.lang.lllegalStateException 开 常 。 


对 于 每 个 默认 连接 ，HttpClient 使 用 SingleClientConnManager。 


2.8.4 连接 池 管 理 器 


ThreadSafeClientConnManager 是 一 个 复杂 的 实现 来 管理 客户 端 连 接 池 ， 它 也 可 以 
从 多 个 执行 线程 中 服务 连接 请 求 。 对 每 个 基本 的 路 由 ， 连 接 都 是 池 管 理 的 。 对 于 路 
由 的 请 求 ， 管 理 器 在 池 中 有 可 用 的 持久 性 连接 ， 将 被 从 池 中 租赁 连接 服务 ， 而 不 是 
创建 一 个 新 的 连接 。 

ThreadSafeClientConnManager 维 护 每 个 基本 路 由 的 最 大 连接 限制 。 每 个 默认 的 实 
现 对 每 个 给 定 路 由 将 会 创建 不 超过 两 个 的 并 发 连接 ， 而 总 共 也 不 会 超过 20 个 连接 。 
对 于 很 多 丨 实 的 应 用 程序 ， 这 个 限制 也 证 明 很 大 的 制约 ， 特 别 是 他 们 在 服务 中 使 用 
HTTP 作 为 传输 协议 。 连 接 限制 ， 也 可 以 使 用 HTTP 参 数 来 进行 调整 。 


这 个 示例 展示 了 连接 池 参 数 是 如 何 来 调整 的 : 


HttpParams params = new BasicHttpParams(); 
// 增加 最 大 连接 到 200 
ConnManagerParams.setMaxTotalConnections(params, 200); 
// 增加 每 个 路 由 的 默认 最 大 连接 到 20 
ConnPerRouteBean connPerRoute = new ConnPerRouteBean( 20); 
// xtlocalhost :80 增 加 最 大 连接 到 50 
HttpHost localhost = new HttpHost("locahost", 80); 
connPerRoute.setMaxForRoute(new HttpRoute(localhost), 50); 
ConnManagerParams.setMaxConnectionsPerRoute(params, connPerRoute 
); 
SchemeRegistry schemeRegistry = new SchemeRegistry(); 
schemeRegistry.register( 

new Scheme("http", PlainSocketFactory.getSocketFactory(), 80 
) ) 
SchemeRegistry.register( 

new Scheme("https", SSLSocketFactory.getSocketFactory(), 443 
)); 
ClientConnectionManager cm = new ThreadSafeClientConnManager (par 
ams, schemeRegistry); 
HttpClient httpClient = new DefaultHttpClient(cm, params); 


2.8.5 连接 管理 器 关闭 


当 一 个 HttpClient 实 例 不 再 需要 时 ， 而 且 即 将 走出 使 用 范围 ， 那 么 关闭 连接 管理 器 来 
保证 由 管理 器 保持 活动 的 所 有 连接 被 关闭 ， 由 连接 分 配 的 系统 资源 被 释放 是 很 重要 
的 。 


DefaultHttpClient httpclient = new DefaultHttpClient(); 
HttpGet httpget = new HttpGet("http://www.google.com/"); 
HttpResponse response = httpclient.execute(httpget); 
HttpEntity entity = response.getEntity(); 
System.out.printiln(response.getStatusLine()); 
if (entity != null) { 

entity.consumeContent(); 


httpclient.getConnectionManager().shutdown(); 


2.9 连接 管理 参数 


这 些 是 可 以 用 于 定制 标准 HTTP 连 接管 理 器 实现 的 参数 : 


e http.conn-manager.timeout :定义 了 当 从 ClientConnectionManager 中 检 
索 ManagedClientConnection 实 例 时 使 用 的 毫秒 级 的 超时 时 间 。 这 个 参数 期 望 
得 到 一 个 java.lang.Long 类 型 的 值 。 如 果 这 个 参数 没有 被 设置 ， 连 接 请 求 就 不 
会 超时 (无 限 大 的 超时 时 间 ) 。 

e http.conn-manager.max-per-route : 定义 了 每 个 路 由 连接 的 最 大 数量 。 
这 个 限制 由 客户 端 连 接管 理 器 来 解释 ， 而 且 应 用 于 独立 的 管理 器 实例 。 这 个 参 


数 期 望 得 到 一 个 ConnPerRoute 类 型 的 值 。 

e http.conn-manager.max-total :定义 了 总 共 连 接 的 最 大 数目 。 这 个 限制 
由 客户 端 连接 管理 器 来 解释 ， 而 且 应 用 于 独立 的 管理 器 实例 。 这 个 参数 期 望 得 
到 一 个 java.lang.Integer 类 型 的 值 。 


2.10 多 线程 执行 请 求 


当 配 备 连 接 池 管 理 器 时 ， 比 如 ThreadSafeClientConnManager，HttpClient 可 以 同 
时 被 用 来 执行 多 个 请 求 ， 使 用 多 线程 执行 。 


ThreadSafeClientConnManager 将 会 分 配 基 于 它 的 配置 的 连接 。 如 果 对 于 给 定 路 由 
的 所 有 连接 都 被 租 出 了 ， 那 么 连接 的 请 求 将 会 阻塞 ， 直 到 一 个 连接 被 释放 回 连 接 

池 。 它 可 以 通过 设置 'http.conn-manager.timeout' 为 一 个 正 数 来 保证 连接 管理 器 不 会 
在 连接 请 求 执行 时 无 限期 的 被 阻塞 。 如 果 和 连接 请 求 不 能 在 给 定 的 时 间 周 期 内 被 响 
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HttpParams params = new BasicHttpParams(); 
SchemeRegistry schemeRegistry = new SchemeRegistry(); 
schemeRegistry.register( 

new Scheme("http", PlainSocketFactory.getSocketFactory(), 80 
)); 
ClientConnectionManager cm = new ThreadSafeClientConnManager (par 
ams, schemeRegistry); 
HttpClient httpClient = new DefaultHttpClient(cm, params); 
// 执行 GET 方 法 的 URI 
String[] urisToGet = { 

"http://www.domaini.com/", 

"http://www.domain2.com/", 

"http://www.domain3.com/", 

"http://www.domain4.com/" 


}; 
// 为 每 个 URI 创 建 一 个 线程 
GetThread[] threads = new GetThread[urisToGet.length]; 
for (int i = 0; i < threads.length; i++) { 
HttpGet httpget = new HttpGet(urisToGet[i]); 
threads[i] = new GetThread(httpClient, httpget); 


// 开始 执行 线程 
for (int j = 0; j < threads.length; j++) { 
threads[j].start(); 


} 

// 合并 线程 

for (int j = 0; j < threads.length; j++) { 
threads[j].join(); 

} 


static class GetThread extends Thread { 

private final HttpClient httpClient; 

private final HttpContext context; 

private final HttpGet httpget; 

public GetThread(HttpClient httpClient, HttpGet httpget) { 
this.httpClient = httpClient; 
this.context = new BasicHttpContext(); 
this.httpget = httpget; 

} 

@Override 

public void run() { 


try { 
HttpResponse response = this.httpClient.execute(this 
.httpget, this.context); 

HttpEntity entity = response.getEntity(); 

if (entity != null) { 
// 对 实体 做 些 有 用 的 事情 ， 
// 保证 连接 能 释放 回 管理 器 
entity.consumeContent(); 


} catch (Exception ex) { 
this. httpget.abort(); 
} 


2.11 连接 收回 策略 


一 个 经 典 的 阻塞 WO 模型 的 主要 缺点 是 网 络 套 接 字 仅 当 1I/O 操 作 阻 塞 时 才 可 以 响应 IO 
事件 。 当 一 个 连接 被 释放 返回 管理 如 时 ， 它 可 以 被 保持 活动 状态 而 却 不 能 监控 套 接 
字 的 状态 和 响应 任何 MO 事件 。 如 果 连 接 在 服务 器 端 关闭 ， 那 么 客户 端 连接 也 不 能 
侦 测 连接 状态 中 的 变化 和 关闭 本 端的 套 接 字 去 作出 适当 响应 。 


HttpClient 通 过 测试 连接 是 否 是 过 时 的 来 尝试 去 减轻 这 个 问题 ， 这 已 经 不 再 有 效 了 ， 
因为 它 已 经 在 服务 器 端 关 闭 了 ， 之 前 使 用 执行 HTTP 请 求 的 连接 。 过 时 的 连接 检查 
也 并 不 是 100% 的 稳定 ， 反 而 对 每 次 请 求 执行 还 要 增加 10 到 30 毫 秒 的 开销 。 唯 一 可 
行 的 而 不 涉及 到 每 个 对 空闲 连接 的 套 接 字模 型 线程 解决 方案 ， 是 使 用 专用 的 监控 线 
程 来 收回 因为 长 时 间 不 活动 而 被 认为 是 过 期 的 连接 。 监 控 线 程 可 以 周期 地 调用 
ClientConnectionManager#closeExpiredConnections() 方 法 来 关闭 所 有 过 期 的 连 


接 ， 从 连接 池 中 收回 关闭 的 连接 。 它 也 可 以 选择 性 调用 
ClientConnectionManager#closeldleConnections() 方 法 来 关闭 所 有 已 经 空闲 超过 
定时 间 周 期 的 连接 。 


public static class IdleConnectionMonitorThread extends Thread { 
private final ClientConnectionManager connMgr; 
private volatile boolean shutdown; 
public IdleConnectionMonitorThread(ClientConnectionManager c 
onnMgr) { 
super(); 
this.connMgr = connMgr; 


} 
@Override 
public void run() { 
try { 
while (!shutdown) { 
synchronized (this) { 
wait(5000); 
// 关闭 过 期 连接 
connMgr. closeExpiredConnections(); 
// 可 选 地 ， 关 闭 空 闲 超过 39 秒 的 连接 
connMgr.closeIdleConnections(30, TimeUnit.SE 
CONDS); 
} 
} catch (InterruptedException ex) { 
// 终止 


} 


public void shutdown() { 
shutdown = true; 
synchronized (this) { 
notifyAll(); 
} 


2.12 IRRA SY RG 


HTTP 规 范 没 有 确定 一 个 持久 连接 可 能 或 应 该 保持 活动 多 长 时 间 。 一 些 HTTP 服 务 器 
使 用 非 标准 的 头 部 信息 Keep-Alive 来 告诉 客户 端 它们 想 在 服务 器 端 保持 连接 活动 的 
周期 秒 数 。 如 果 这 个 信息 可 用 ，HttClient 就 会 利用 这 个 它 。 如 果 头 部 信息 Keep- 
Alive 在 响应 中 不 存在 ，HttpClient 假 设 连 接 无 限期 的 保持 活动 。 然 而 许多 现实 中 的 
HTTP 服 务 器 配置 了 在 特定 不 活动 周期 之 后 丢掉 持久 连接 来 保存 系统 资源 ， 往 往 这 
是 不 通知 客户 端的 。 如 果 默 认 的 策略 证 明 是 过 于 乐观 的 ， 那 么 就 会 有 人 想 提 供 一 个 
定制 的 保持 活动 策略 


DefaultHttpClient httpclient = new DefaultHttpClient(); 
httpclient.setKeepAliveStrategy(new ConnectionKkKeepAliveStrategy( 
) i 
public long getKeepAliveDuration(HttpResponse response, Http 
Context context) { 
// 兑现 'keep-alive' 头 部 信息 
HeaderElementIterator it = new BasicHeaderElementIterato 


r( 

response.headerIterator(HTTP.CONN_KEEP_ALIVE)); 

while (it.hasNext()) { 

HeaderElement he = it.nextElement(); 

String param = he.getName(); String value = he.getVa 
lue(); 

if (value != null && param.equalsIgnoreCase("timeout 
DD A 

try { 


return Long.parseLong(value) * 1000; 
} catch(NumberFormatException ignore) { 
} 
} 
} 
HttpHost target = (HttpHost) context.getAttribute( 
ExecutionContext.HTTP_TARGET_HOST); 
if ("www.naughty-server.com".equalsIgnoreCase(target.get 
HostName())) { 
// 只 保持 活动 5 秒 
return 5 * 1000; 
} else { 
// 否则 保持 活动 30 秒 
return 30 * 1000; 


}); 


第 三 章 HTTP 状 态 管理 


原始 的 HTTP 是 被 设计 为 无 状态 的 ， 面 向 请 求 /响应 的 协议 ， 没 有 特殊 规定 有 状态 
的 ， 贯 穿 一 些 逻 辑 相 关 的 请 求 /响应 交换 的 会 话 。 由 于 HTTP 协 议 变 得 越 来 越 普及 和 
受 欢迎 ， 越 来 越 多 的 从 前 没有 打算 使 用 它 的 系统 也 开始 为 应 用 程序 来 使 用 它 ， 比 如 
作为 电子 商务 应 用 程序 的 传输 方式 。 因 此 ， 支 持 状 态 管理 就 变 得 非常 必要 了 。 


网 景 公 司 ， 一 度 成 为 Web 客 户 端 和 服务 器 软件 开发 者 的 领导 方向 ， 在 它们 基于 专 有 
规范 的 产品 中 实现 了 对 HTTP 状 态 管 理 的 支持 。 之 后 ， 网 景 公司 试图 通过 发 布 规范 
草案 来 规范 这 种 机 制 。 它 们 的 努力 通过 RFC 标 准 跟踪 促成 了 这 些 规范 定 义 。 然 而 ， 
在 很 多 应 用 程序 中 的 状态 管理 仍然 基于 网 景 公司 的 草案 而 不 兼容 官方 的 规范 。 很 多 
主要 的 Web 浏 览 器 开发 者 觉得 有 必要 保留 那些 极 大 促进 标准 片段 应 用 程序 的 兼容 
性 o 


3.1 HTTP cookies 


Cookie 是 HTTP 代 理 和 目标 服务 器 可 以 交流 保持 会 话 的 状态 信 息 的 令 牌 或 短 包 。 网 
景 公司 的 工程 师 用 它 来 指 “" 魔 法 小 甜 饼 ?和 粘 住 的 名 字 。 


HttpClient 使 用 Cookie 接 口 来 代表 抽象 的 cookie 令 牌 。 在 它 的 简单 形式 中 HTTP 的 
cookie 几乎 是 名 / 值 对 。 通 常 一 个 HTTP 的 cookie 也 包含 一 些 属 性 ， 比 如 版 本 号 ， 合 
法 的 域名 ， 指 定 cookie 应 用 所 在 的 源 服 务 器 URL 子 集 的 路 径 ，cookie 的 最 长 有 效 时 
间 。 


SetCookie 接 口 代 表 由 源 服 务 器 发 送 给 HTTP 代 理 的 响应 中 的 头 部 信息 Set-Cookie 来 
维持 一 个 对 话 状 态 。SetCookie2 接 口 和 指定 的 Set-Cookie2 方 法 扩展 了 SetCookie ° 


SetCookie 接 口 和 额外 的 如 获取 原始 cookie 属 性 的 能 力 ， 就 像 它们 由 源 服务 器 指定 
的 客户 端 特定 功能 扩展 了 Cookie 接 口 。 这 对 生成 Cookie 头 部 很 重要 ， 因 为 一 些 
cookie 规 范 需要 。Cookie 关 部 应 该 包含 在 Set-Cookie 或 Set-Cookie2 头 部 中 指定 的 
特定 属性 。 


3.1.1 Cookie 版 本 


Cookie 兼 容 网 景 公司 的 草案 标准 ， 但 是 版 本 0 被 认为 是 不 符合 官方 规范 的 。 符 合 标 
准 的 cookie 的 期 望 版 本 是 1。HttpClient 可 以 处 理 基于 不 同 版 本 的 cookie 。 


这 里 有 一 个 重新 创建 网 景 公司 草案 cookie 示 例 : 


BasicClientCookie netscapeCookie = new BasicClientCookie("name", 
"value"); 

netscapeCookie.setVersion(0); 

netscapeCookie.setDomain(".mycompany.com" ); 

netscapeCookie.setPath("/"); 


这 是 一 个 重新 创建 标准 cookie 的 示例 。 要 注意 符合 标准 的 cookie 必 须 保 留 由 源 服 务 
器 发 送 的 所 有 属性 : 


BasicClientCookie stdCookie = new BasicClientCookie("name", "val 
ue"); 

stdCookie.setVersion(1); 

stdCookie.setDomain(".mycompany.com"); 

stdCookie.setPath("/"); 

a a 

// 精确 设置 由 服务 器 发 送 的 属性 
stdCookie.setAttribute(ClientCookie.VERSION_ATTR, "1"); 
stdCookie.setAttribute(ClientCookie.DOMAIN_ATTR, ".mycompany.com 


")i 


这 是 一 个 重新 创建 Set-Cookie2 兼 容 cookie 的 实例 。 要 注意 符合 标准 的 cookie 儿 须 保 
留 由 源 服 务 器 发 送 的 所 有 属性 : 


BasicClientCookie2 stdCookie = new BasicClientCookie2("name", "v 
alue"); 

stdCookie.setVersion(1); 

stdCookie.setDomain(".mycompany.com"); 

stdCookie.setPorts(new int[] {80,8080}); 

stdCookie.setPath("/"); 

Tap se eee 

// 精确 设置 由 服务 器 发 送 的 属性 
stdCookie.setAttribute(ClientCookie.VERSION_ATTR, "1"); 
stdCookie.setAttribute(ClientCookie.DOMAIN_ATTR, ".mycompany.com 
"); 

stdCookie.setAttribute(ClientCookie.PORT_ATTR, "80,8080"); 


3.2 Cookie#2 7% 


CookieSpec 接 口 代表 了 cookie 管 理 的 规范 。Cookie 管 理 规范 希望 如 下 几 点 : 


e 解析 的 Set-Cookie 规 则 还 有 可 选 的 Set-Cookie2 头 部 信息 。 
e 验证 解析 cookie 的 规则 o 
© 格式 化 给 定 主 机 的 Cookie 头 部 信息 ， 原 始 端口 和 路 径 。 


HttpClient 附 带 了 一 些 CookieSpec 的 实现 : 


e 网 景 公司 草案 : 这 个 规范 符合 由 网 景 通讯 发 布 的 原始 草案 规范 。 应 当 避 免 ， 除 
非 有 绝对 的 必要 去 兼容 遗留 代码 。 

e RFC 2109 : È 方 HTTP 状 态 管理 规 T ANERE > 被 RFC 2965 取 代 。 

e RFC 2965 : 官方 HTTP 状 态 管理 规范 

° 浏览 器 兼容 性 这 个 实现 努力 去 密切 模 1 仿 (mis) 通用 Web 浏 览 器 应 用 程序 的 
实现 。 比 如 微软 的 Internet aa FireFox 浏 览 器 。 

e 最 佳 匹配 : Meta (元 ) cookie 规 范 采 用 了 一 些 基 于 又 HTTP 响 应 发 送 的 cookie 


格式 的 cookie 策 略 。 它 基本 上 聚合 了 以 上 所 有 的 实现 到 以 一 个 类 中 。 


强烈 建议 使 用 Best Match 策 略 ， 让 HttpClient 在 运行 时 基于 执行 上 下 文采 用 一 些 合适 
的 兼容 等 级 。 


3.3 HTTP cookie 和 状态 管理 参数 


这 些 是 用 于 定制 HTTP 状 态 管理 和 独立 的 cookie 规 范 行为 的 参数 。 


e 'http.protocol.cookie-datepatterns' : 定义 了 用 于 解析 非 标 准 的 expires 属 性 的 合 
法 日 期 格式 。 只 是 对 兼容 不 符合 规定 的 ， 仍 然 使 用 网 景 公 司 草 案 定义 的 expires 
而 不 使 用 标准 的 max-age 属 性 服务 器 需要 。 这 个 参数 期 望 得 到 一 个 
java.util.Collection 类 型 的 值 。 集 合 元 素 必须 是 java.lang.String 类 型 ， 来 兼容 
java.text.SimpleDateFormat 的 语法 。 如 果 这 个 参数 没有 被 设置 ， 那 么 默认 的 选 
择 就 是 CookieSpec 实 现 规范 的 值 。 要 注意 这 个 参数 的 应 用 。 
'http.protocol.single-cookie-header' : 定义 了 是 否 cookie 应 该 强制 到 一 个 独立 的 
Cookie 请 求 头 部 信息 中 。 否 则 ， 每 个 cookie 就 被 当 作 分 离 的 Cookie 头 部 信息 来 
格式 化 。 这 个 参数 期 望 得 到 一 个 java.lang.Boolean 类 型 的 值 。 如 果 这 个 参数 没 
有 被 设置 ， 那 么 默认 的 选择 就 是 CookieSpec 实 现 规范 的 值 。 要 注意 这 个 参数 仅 
仅 严 格 应 用 于 cookie 规 范 (RFC 2109 和 RFC 2965) 。 浏 览 器 兼容 性 和 网 景 公 
司 草 案 策 略 将 会 放置 所 有 的 cookie 到 一 个 请 求 头 部 信息 中 。 
'http.protocol.cookie-policy' : 定义 了 用 于 HTTP 状 态 管理 的 cookie 规 范 的 名 

字 。 这 个 参数 期 望 得 到 一 个 java.lang.String 类 型 的 值 。 如 果 这 个 参数 没有 被 设 
置 ， 那 么 合法 的 日 期 格式 就 是 CookieSpec 实 现 规 范 的 值 。 


3.4 Cookie 规 范 注册 表 


HttpClient 使 用 CookieSpecRegistry 类 维护 一 个 可 用 的 cookie 规 范 注册 表 。 下 面 的 规 
范 对 于 每 个 默认 都 是 注册 过 的 : 

。 兼容 性 : 浏览 器 兼容 性 (宽松 策略 ) 。 

eo 网 景 :网 景 公司 草案 。 

e rfc2109 : RFC 2109 (过 时 的 严格 策略 ) © 

e rfc2965 : RFC 2965 (严格 策略 的 标准 符合 ) 。 

e best-match : 最 佳 匹 配 meta (元 ) 策略 。 


3.5 选择 cookie 策 略 


Cookie 策 略 可 以 在 HTTP 客 户 端 被 设置 ， 如 果 需 要 ， 在 HTTP 请 求 级 重 写 。 


HttpClient httpclient = new DefaultHttpClient(); 
// 对 每 个 默认 的 强制 严格 cookie 策 略 
httpclient.getParams().setParameter( 

ClientPNames.COOKIE_POLICY, CookiePolicy.RFC_2965); 
HttpGet httpget = new HttpGet("http://www.broken-server.com/"); 
// 对 这 个 请 求 覆盖 默认 策略 
httpget.getParams().setParameter( 

ClientPNames.COOKIE_POLICY, CookiePolicy.BROWSER_COMPATIBILI 
TY); 


3.6 定制 cookie 策 略 


为 了 实现 定制 cookie 策 略 ， 我 们 应 该 创建 CookieSpec 接 口 的 定制 实现 类 ， 创 建 一 个 
CookieSpecFactory 实 现 来 创建 和 初始 化 定制 实现 的 实例 并 和 HttpClient 注 册 这 个 工 
厂 。 一 旦 定制 实现 被 注册 了 ， 它 可 以 和 标准 的 cookie 实 现 有 相同 的 活性 。 


CookieSpecFactory csf = new CookieSpecFactory() { 
public CookieSpec newInstance(HttpParams params) { 
return new BrowserCompatSpec() { 

@Override 

public void validate(Cookie cookie, CookieOrigin ori 
gin) 

throws MalformedCookieException { 

// 这 相当 简单 
} 


Pr 


} 
}; 
DefaultHttpClient httpclient = new DefaultHttpClient(); 
httpclient.getCookieSpecs().register("easy", csf); 
httpclient.getParams().setParameter( 
ClientPNames.COOKIE_POLICY, "easy"); 


3.7 Cookie 持 久 化 


HttpClient 可 以 和 任意 物理 表示 的 实现 了 CookieStore 接 口 的 持久 化 cookie 存 储 一 起 
使 用 。 默 认 的 CookieStore 实 现 称 为 BasicClientCookie， 这 是 凭借 java.util.ArrayList 
的 一 个 简单 实现 。 在 BasicClientCookie 对 象 中 存储 的 cookie 当 容器 对 象 被 垃圾 回收 
机 制 回收 时 会 丢失 。 如 果 需 要 ， 用 户 可 以 提供 更 复杂 的 实现 。 


DefaultHttpClient httpclient = new DefaultHttpClient(); 
// 创建 一 个 本 地 的 cookie store 实 例 

CookieStore cookieStore = new MyCookieStore(); 

// wR ARE cookie 

BasicClientCookie cookie = new BasicClientCookie("name", "value" 
); 

cookie.setVersion(0); 
cookie.setDomain(".mycompany.com"); 
cookie.setPath("/"); 

cookieStore.addCookie(cookie); 

// 设置 存储 

httpclient.setCookieStore(cookieStore) ) 


3.8 HTTP 状 态 管理 和 执行 上 下 文 


在 HTTP 请 求 执行 的 过 程 中 ，HttpClient 添 加 了 下 列 和 状态 管理 相关 的 对 象 到 执行 上 
Tepi 


e http.cookiespec-registry : CookieSpecRegistry 实 例 代 表 了 实际 的 
cookie 规 范 注册 表 。 这 个 属性 的 值 设 置 在 本 地 内 容 中 ， 优 先 于 默认 的 。 

e http.cookie-spec : CookieSpec È #] KR 4 È A cookies i © 

e http.cookie-origin : CookieOrigin # AAT AR RI J BY Fas 
息 。 

e http.cookie-store : CookieStore 实 例 代 表 了 缆 实 的 cookie 存 储 。 设 置 在 
本 地 内 容 中 的 这 个 属性 的 值 优 先 于 默认 的 。 


本 地 的 HttpContext 对 象 可 以 被 用 来 定制 HTTP 状 态 管理 内 容 ， 先 于 请 求 执行 或 在 请 
求 执行 之 后 检查 它 的 状态 : 


HttpClient httpclient = new DefaultHttpClient(); 
HttpContext localContext = new BasicHttpContext(); 
HttpGet httpget = new HttpGet("http://localhost:8080/"); 
HttpResponse response = httpclient.execute(httpget, localContext 
); 
CookieOrigin cookieorigin = (CookieOrigin) localContext.getAttri 
bute( 
ClientContext.COOKIE_ORIGIN); 
System.out.printiln("Cookie origin: " + cookieOrigin); 
CookieSpec cookieSpec = (CookieSpec) localContext.getAttribute( 
ClientContext .COOKIE_SPEC); 
System.out.println("Cookie spec used: " + cookieSpec); 


3.9 每 个 用 户 / 线 程 的 状态 管理 


我 们 可 以 使 用 独立 的 本 地 执行 上 下 文 来 实现 对 每 个 用 户 (或 每 个 线程 ) 状态 的 管 
理 。 定 义 在 本 地 内 容 中 的 cookie 规 范 注册 表 和 cookie 存 储 将 会 优先 于 设置 在 HTTP 客 
户 端 级 别 中 默认 的 那些 。 


HttpClient httpclient = new DefaultHttpClient(); 

// *\#cookie store 的 本 地 实例 

CookieStore cookieStore = new BasicCookieStore(); 

// 创建 本 地 的 HTTP 内 容 

HttpContext localContext = new BasicHttpContext(); 

// 绑 定 定制 的 cookie store 到 本 地 内 容 中 
localContext.setAttribute(ClientContext.COOKIE_STORE, cookieStor 
e); 

HttpGet httpget = new HttpGet("http://www.google.com/"); 

// 作为 参数 传递 本 地 内 容 

HttpResponse response = httpclient.execute(httpget, localContext 


) 


第 四 章 HTTP 认 证 


HttpClient 提 供 对 由 HTTP 标 准 规范 定义 的 认证 模式 的 完全 支持 。HttpClient 的 认证 杠 
架 可 以 扩展 支持 非 标准 的 认证 模式 ， 比 如 NTLM 和 SPNEGO 。 


4.1 F P ETE 


任何 用 户 身 份 验证 的 过 程 都 需要 一 组 可 以 用 于 建立 用 户 身 份 的 凭据 。 用 户 赁 证 的 最 
简单 的 形式 可 以 仅仅 是 用 户 名 /密码 对 。UsernamePasswordCredentials 代 表 了 一 组 
包含 安全 规则 和 明文 密码 的 凭据 。 这 个 实现 对 由 HTTP 标 准 规范 中 定义 的 标准 认证 
模式 是 足够 的 


UsernamePasswordCredentials creds = new UsernamePasswordCredenti 
als("user", "pwd"); 
System.out.println(creds.getUserPrincipal().getName()); 
System.out.printin(creds.getPassword()); 


输出 内 容 为 : 


user 
pwd 


NTCredentials 是 微软 Windows 指 定 的 实现 ， 它 包含 了 除了 用 户 名 /密码 对 外 ， 一 组 
额外 的 Windows 指 定 的 属性 ， 比 如 用 户 域 名 的 名 字 ， 比 如 在 微软 的 Windows 网 络 
中 ， 相 同 的 用 户 使 用 不 同 设置 的 认证 可 以 属于 不 同 的 域 。 
NTCredentials creds = new NTCredentials("user", "pwd", "workstat 
ion", "domain"); 


System.out.println(creds.getUserPrincipal().getName()); 
System.out.println(creds.getPassword()); 


输出 内 容 为 : 
DOMAIN/user 
pwd 

4.2 认证 模式 


AuthScheme 接 口 代表 了 抽象 的 ， 面 向 挑战 -响应 的 认证 模式 。 一 个 认证 模式 期 望 支 
持 如 下 的 功能 : 


o 解析 和 处 理由 目标 服务 器 在 对 受 保 护 资源 请 求 的 响应 中 发 回 的 挑战 。 

o 提供 处 理 挑战 的 属性 : 认证 模式 类 型 和 它 的 参数 ， 如 果 可 用 ， 比 如 这 个 认证 模 
型 可 应 用 的 领域 。 

o 对 给 定 的 赁 证 组 和 HTTP 请 求 对 响应 真实 认证 挑战 生成 认证 字符 串 。 


要 注意 认证 模式 可 能 是 有 状态 的 ， 涉 及 一 系列 的 挑战 -响应 交流 。 HttpClient 附 带 了 
一 些 AuthScheme 实 现 : 


e Basic (基本 ) : Basic 认 证 模式 定义 在 RFC 2617 中 。 这 个 认证 模式 是 不 安全 
的 ， 因 为 凭据 以 明文 形式 传送 。 尽 管 它 不 安全 ， 如 果 用 在 和 TLS/SSL 加 密 的 组 
合 中 ，Basic 认 证 模式 是 完全 够 用 的 。 

e Digest (摘要 ) : Digest 认 证 模式 定义 在 RFC 2617 中 。Digest 认 证 模式 比 
Basic 有 显著 的 安全 提升 ， 对 不 想 通 过 TLS/SL 加 密 在 完全 运输 安全 上 开销 的 应 
用 程序 来 说 也 是 很 好 的 选择 。 

e NTLM : NTLM 是 一 个 由 微软 开发 的 优化 Windows 平 台 的 专 有 认证 模式 。NTLM 
被 认为 是 比 Digest 更 安全 的 模式 。 这 个 模式 需要 外 部 的 NTLM 引 擎 来 工作 。 要 
获取 更 多 详情 请 参考 包含 在 HttpClient 发 布 包 中 的 NTLM_SUPPORT.txt 文 档 。 


4.3 HTTP 认 证 参数 


有 一 些 可 以 用 于 定制 HTTP 认 证 过 程 和 独立 认证 模式 行为 的 参数 : 


e http.protocol.handle-authentication :定义 了 是 否认 证 应 该 被 自动 处 
理 。 这 个 参数 期 望 的 得 到 一 个 java.lang.Boolean 类 型 的 值 。 如 果 这 个 参数 没有 
被 设置 ，HttpClient 将 会 自动 处 理 认证 。 

e http.auth.credential-charset :定义 了 当 编 码 用 户 赁 证 时 使 用 的 字符 
集 。 这 个 参数 期 望 得 到 一 个 java.lang.String 类 型 的 值 。 如 果 这 个 参数 没有 被 设 
置 ， 那 么 就 会 使 用 US-ASCII。 


4.4 认证 模式 注册 表 
HttpClient 使 用 AuthSchemeRegistry 类 维护 一 个 可 用 的 认证 模式 的 注册 表 。 对 于 每 
个 默认 的 下 面 的 模式 是 注册 过 的 : 

e Basic : 基本 认证 模式 

e Digest : 摘要 认证 模式 
请 注意 NTLM 模 式 没有 对 每 个 默认 的 进行 注册 。NTLM 不 能 对 每 个 默认 开启 是 应 为 
许可 和 法 律 上 的 原因 。 要 获取 更 详细 的 关于 如 何 开启 NTLM 支 持 的 内 容 请 看 这 部 


分 。 


4.5 RIERA SS 


凭据 提供 器 意 来 维护 一 组 用 户 赁 据 ， 还 有 能 够 对 特定 认证 范围 生产 用 户 赁 据 。 认 证 
范围 包括 主机 名 ， 端 口号 ， 领 域名 称 和 认证 模式 名 称 。 当 使 用 凭据 提供 器 来 注册 任 
据 时 ， 我 们 可 以 提供 一 个 通配符 (任意 主机 ， 任 意 端口 ， 任 意 领 域 ， 任 意 模式 ) 来 


替代 确定 的 属性 值 。 如 果 直 接 匹配 没有 发 现 ， 赁 据 提 供 器 期 望 被 用 来 发 现 最 匹配 的 
特定 范围 。 


HttpClient 可 以 和 任意 实现 了 CredentialsProvider 接 口 的 凭据 提供 器 的 物理 代表 一 同 
工作 。 上 默认 的 CredentialsProvider 实 现 被 称 为 BasicCredentialsProvider， 它 是 简单 
a) %& fa java.util. HashMap 49 & HL o 


CredentialsProvider credsProvider = new BasicCredentialsProvider 
(); 
credsProvider.setCredentials( 

new AuthScope("somehost", AuthScope.ANY_PORT), 

new UsernamePasswordCredentials("ui", "pi")); 
credsProvider.setCredentials( 

new AuthScope("somehost", 8080), 

new UsernamePasswordCredentials("u2", "p2")); 
credsProvider .setCredentials( 

new AuthScope("otherhost", 8080, AuthScope.ANY_REALM, "ntlm" 
), 

new UsernamePasswordCredentials("u3", "p3")); 
System.out.println(credsProvider .getCredentials( 

new AuthScope("somehost", 80, "realm", "basic"))); 
System.out.println(credsProvider .getCredentials( 

new AuthScope("somehost", 8080, "realm", "basic"))); 
System.out.println(credsProvider .getCredentials( 

new AuthScope("otherhost", 8080, "realm", "basic"))); 
System.out.println(credsProvider .getCredentials( 

new AuthScope("otherhost", 8080, null, "ntlm"))); 


输出 内 容 为 : 


[principal: u1] 
[principal: u2] 
null 

[principal: u3] 


4.6 HTTP 认 证 和 执行 上 下 文 


HttpClient 依 赖 于 AuthState 类 来 跟踪 关于 认证 过 程 状态 的 详细 信息 。 在 HTTP 请 求 执 
行 过 程 中 ，HttpClient 创 建 2 个 AuthState 的 实例 : 一 个 对 于 目标 主机 认证 ， 另 外 一 个 
对 于 代理 认证 。 如 果 目 标 服务 器 或 代理 需要 用 户 认 证 ， 那 么 各 自 的 AuthState 实 例 将 
会 被 在 认证 处 理 过 程 中 使 用 的 AuthScope，AuthScheme 和 Crednetials 来 填充 。 
AuthState 可 以 被 检查 来 找 出 请 求 的 认证 是 什么 类 型 的 ， 是 否 匹 配 AuthScheme 的 实 
现 ， 是 否 凭据 提供 器 对 给 定 的 认证 范围 去 找 用 户 凭据。 


在 HTTP 请 求 执 行 的 过 程 中 ，HttpClient 添 加 了 下 列 和 认证 相关 的 对 象 到 执行 上 下 文 
中 : 


e http.authscheme-registry : AuthSchemeRegistry 实 例 代 表 织 实 的 认证 模 
式 注 册 表 。 在 本 地 内 容 中 设置 的 这 个 属性 的 值 优 先 于 默认 的 。 

e http.auth.credentials-provider : CookieSpec% #| AA T AKA ETE 
提供 器 。 在 本 地 内 容 中 设置 的 这 个 属性 的 值 优先 于 默认 的 。 

e http.auth.target-scope : AuthState 实 例 代 表 了 旨 实 的 目标 认证 状态 。 在 
本 地 内 容 中 设置 的 这 个 属性 的 值 优 先 于 默认 的 。 

e http.auth.proxy-scope : AuthState 实 例 代 表 了 申 实 的 代理 认证 状态 。 在 
本 地 内 容 中 设置 的 这 个 属性 的 值 优 先 于 默认 的 。 


本 地 的 HttpContext 对 象 可 以 用 于 定制 HTTP 认 证 内 容 ， 并 先 于 请 求 执行 或 在 请 求 被 
执行 之 后 检查 它 的 状态 : 


HttpClient httpclient = new DefaultHttpClient(); 

HttpContext localContext = new BasicHttpContext(); 

HttpGet httpget = new HttpGet("http://localhost:8080/") ; 
HttpResponse response = httpclient.execute(httpget, localContext 


); 
AuthState proxyAuthState = (AuthState) localContext.getAttribute 


( 

ClientContext .PROXY_AUTH_STATE); 
System.out.println("Proxy auth scope: " + proxyAuthState.getAuth 
Scope()); 
System.out.println("Proxy auth scheme: " + proxyAuthState.getAut 
hScheme()); 
System.out.println("Proxy auth credentials: " + proxyAuthState.g 
etCredentials()); 
AuthState targetAuthState = (AuthState) localContext.getAttribut 
e( 

ClientContext .TARGET_AUTH_STATE) ; 
System.out.printin("Target auth scope: " + targetAuthState.getAu 
thScope()); 
System.out.printin("Target auth scheme: " + targetAuthState.getA 
uthScheme()); 
System.out.println("Target auth credentials: " + targetAuthState 
.getCredentials()); 


4.7 抢占 认证 


HttpClient 不 支持 开 箱 的 抢占 认证 ， 因 为 滥用 或 重用 不 正确 的 抢占 认证 可 能 会 导致 严 
重 的 安全 问题 ， 比 如 将 用 户 赁 据 以 明文 形式 发 送 给 未 认证 的 第 三 方 。 因 此 ， 用 户 期 
望 评估 抢占 认证 和 在 它们 只 能 应 用 程序 环境 内 容 安 全 风险 潜在 的 好 处 ， 而 且 要 求 使 
用 如 协议 拦截 器 的 标准 HttpClient 扩 展 机 制 添 加 对 抢占 认证 的 支持 。 


这 是 一 个 简单 的 协议 拦截 器 ， 如 果 没 有 企图 认证 ， 来 抢先 引入 BasicScheme 的 实例 
到 执行 上 下 文中 。 请 注意 拦截 器 必须 在 标准 认证 拦截 器 之 前 加 入 到 协议 处 理 链 中 。 


HttpRequestInterceptor preemptiveAuth = new HttpRequestIntercept 
or() { 
public void process(final HttpRequest request, 
final HttpContext context) throws HttpException, IOException 
{ 
AuthState authState = (AuthState) context.getAttribute( 
ClientContext .TARGET_AUTH_STATE); 
CredentialsProvider credsProvider = (CredentialsProvider 
) context.getAttribute(ClientContext.CREDS PROVIDER); 
HttpHost targetHost = (HttpHost) context.getAttribute( 
ExecutionContext .HTTP_TARGET_HOST ) ; 
// 如 果 没 有 初始 化 auth 模 式 
if (authState.getAuthScheme() == null) { 
AuthScope authScope = new AuthScope( 
targetHost.getHostName(), 
targetHost.getPort()); 
// 获得 匹配 目标 主机 的 凭据 
Credentials creds = credsProvider.getCredentials(aut 


hScope); 
// 如 果 发 现 了 ， 抢 先生 成 BasicScheme 
if (creds != null) { 
authState.setAuthScheme(new BasicScheme()); 
authState.setCredentials(creds); 
} 
} 
} 
J; 


DefaultHttpClient httpclient = new DefaultHttpClient(); 
// 作为 第 一 个 拦截 器 加 入 到 协议 链 中 
httpclient.addRequestInterceptor(preemptiveAuth, 0); 


4.8 NTLM 认证 


当前 HttpClient 没 有 提 对 开 箱 的 NTLM 认 证 模式 的 支持 也 可 能 永远 也 不 会 。 这 个 原 
是 法 律 上 的 而 不 是 技术 上 的 。 然 而 ，NTLM 认 证 可 以 使 用 外 部 的 NTLM 引 擎 比如 
JCIFS 来 开启 ， 类 库 由 Samba 项 目 开 发 ， 作 为 它们 Windows 的 交互 操作 程序 套装 的 
一 部 分 。 要 获取 详细 内 容 请 参考 HttpClient 发 行 包 中 包含 的 NTLM_SUPPORT.txt 文 
档 。 


4.8.1 NTLM 连 接 持 久 化 


NTLM 认 证 模式 是 在 计算 开销 方面 品 贵 的 多 的 ， 而 且 对 标准 的 Basic 和 Digest 模 式 的 
性 能 影响 也 很 大 。 这 很 可 能 是 为 什么 微软 选择 NTLM 认 证 模式 为 有 状态 的 主要 原 
之 一 。 也 就 是 说 ， 一 旦 认证 通过 ， 用 户 标识 是 和 连接 的 整个 生命 周期 相关 联 的 。 
NTLM 连 接 的 状态 特性 使 得 连接 持久 化 非常 复杂 ， 对 于 明显 的 原因 ， 持 久 化 NTLM 
连接 不 能 被 使 用 不 同 用 户 标 识 的 用 户 重 用 。 标 准 的 连接 管理 器 附带 HttpClient 是 完全 
能 够 管理 状态 连接 的 。 而 逻辑 相关 的 ， 使 用 同一 session 和 执行 上 下 文 为 了 让 它们 了 


解 到 当前 的 用 户 标识 的 请 求 也 是 极为 重要 的 。 否 则 ，HttpClient 将 会 终止 对 每 个 基于 
NTLM 保 护 资源 的 HTTP 请 求 创 建新 的 HTTP 连 接 。 要 获取 关于 有 状态 的 HTTP 连 接 
的 详细 讨论 ， 请 参考 这 个 部 分 。 


因为 NTLM 连 接 是 有 状态 的 ， 通 常 建议 使 用 相对 简单 的 方法 触发 NTLM 认 证 ， 比 如 
GET 或 HEAD > 而 重用 相同 的 连接 来 执行 代价 更 大 的 方法 ， 特 别 是 它们 包含 请 求实 
体 ， 比 如 POST 或 PUT。 


DefaultHttpClient httpclient = new DefaultHttpClient(); 
NTCredentials creds = new NTCredentials("user", "pwd", "myworkst 
ation", "microsoft.com"); 
httpclient.getCredentialsProvider().setCredentials(AuthScope. ANY 
, Creds); 
HttpHost target = new HttpHost("www.microsoft.com", 80, "http"); 
// 保证 相同 的 内 容 来 用 于 执行 逻辑 相关 的 请 求 
HttpContext localContext = new BasicHttpContext(); 
// 首先 执行 简便 的 方法 。 这 会 触发 NTLM 认 证 
HttpGet httpget = new HttpGet("/ntlm-protected/info"); 
HttpResponse responsei = httpclient.execute(target, httpget, loc 
alContext); 
HttpEntity entity1 = response1.getEntity(); 
if (entity1i != null) { 

entity1.consumeContent(); 


} 
// 之 后 使 用 相同 的 内 容 (和 连接 ) 执行 开销 大 的 方法 。 
HttpPost httppost = new HttpPost("/ntlm-protected/form") ; 
httppost.setEntity(new StringEntity("lots and lots of data")); 
HttpResponse response2 = httpclient.execute(target, httppost, lo 
calContext); 
HttpEntity entity2 = response2.getEntity(); 
if (entity2 != null) { 

entity2.consumeContent(); 


} 


第 五 章 HTTP 客 户 端 服务 


5.1 HttpClient!] ®© 


HttpClient 接 口 代 表 了 最 重要 的 HTTP 请 求 执行 的 契约 。 它 没有 在 请 求 执行 处 理 上 强 
加 限制 或 特殊 细节 ， 而 在 连接 管理 ， 状 态 管理 ， 认 证 和 处 理 重 定向 到 具体 实现 上 留 
下 了 细节 。 这 应 该 使 得 很 容易 使 用 额外 的 功能 ， 比 如 响应 内 容 缓存 来 装饰 接口 。 


DefaultHttpClient 是 HttpClient 接 口 的 默认 实现 。 这 个 类 扮演 了 很 多 特殊 用 户 程序 或 
策略 接口 实现 负责 处 理 特定 HTTP 协 议 方面 ， 比 如 重 定向 到 处 理 认证 或 做 出 关于 连 
接 持久 化 和 保持 活动 的 持续 时 间 决 定 的 门面 。 这 使 得 用 户 可 以 选择 使 用 定制 ， 具 体 
程序 等 来 替换 某 些 方面 默认 实现 。 


DefaultHttpClient httpclient = new DefaultHttpClient(); 
httpclient.setKeepAliveStrategy(new DefaultConnectionkKeepAliveSt 
rategy() { 
@Override 
public long getKeepAliveDuration(HttpResponse response, 
HttpContext context) { 
long keepAlive = super.getKeepAliveDuration(response, co 
ntext); 
if (keepAlive == -1) { 
// 如 果 keep-alive 值 没有 由 服务 器 明确 设置 ， 那 么 保持 连接 持续 5 秒 


keepAlive = 5000; 


return keepAlive; 
} 
}); 


DefaultHttpClient 也 维护 一 组 协议 拦截 器 ， 意 在 处 理 即将 离开 的 请 求 和 即将 到 达 的 
响应 ， 而 且 提供 管理 那些 拦截 器 的 方法 。 新 的 协议 拦截 器 可 以 被 引入 到 协议 处 理 器 
链 中 ， 或 在 需要 时 从 中 移 除 。 内 部 的 协议 拦截 器 存储 在 一 个 简单 的 
java.util.ArrayList 中 。 它 们 以 被 加 入 到 list 中 的 自然 顺序 来 执行 。 


DefaultHttpClient httpclient = new DefaultHttpClient(); 
httpclient.removeRequestInterceptorByClass(RequestUserAgent.clas 
s); 
httpclient.addRequestInterceptor(new HttpRequestInterceptor() { 
public void process( 
HttpRequest request, HttpContext context) 
throws HttpException, IOException { 
request.setHeader(HTTP.USER_AGENT, "My-own-client"); 
} 


}); 


DefaultHttpClient 是 线程 安全 的 。 建 议 相 同 的 这 个 类 的 实例 被 重用 于 多 个 请 求 的 执 


行 。 
理 器 


当 一 个 DefaultHttpClient 实 例 不 再 需要 而 且 要 脱离 范围 时 ， 和 它 关联 的 连接 管 
必须 调用 ClientConnectionManager#shutdown() 方 法 关闭 。 


HttpClient httpclient = new DefaultHttpClient(); 
// 做 些 有 用 的 事 
httpclient.getConnectionManager().shutdown(); 


5.2 HttpClient# 2 


是 可 以 用 于 定制 默认 HttpClient 实 现行 为 的 参数 : 


http.protocol.handle-redirects : 定义 了 重 定 向 是 否 应 该 自动 处 理 。 这 
个 参数 期 望 得 到 一 个 java.lang.Boolean 类 型 的 值 。 如 果 这 个 参数 没有 被 设置 ， 
HttpClient 将 会 自动 处 理 重 定向 。 

http.protocol.reject-relative-redirect :定义 了 是 否 相 对 的 重 定向 应 
该 被 拒绝 。HTTP 规 范 需 要 位 置 值 是 一 个 绝对 URI。 这 个 参数 期 望 得 到 一 个 
java.lang.Boolean 类 型 的 值 。 如 果 这 个 参数 没有 被 设置 ， 那 么 就 允许 相对 重 定 
向 。 

http.protocol.max-redirects :定义 了 要 遵循 重 定向 的 最 大 数量 。 这 个 
重 定向 数字 的 限制 意 在 防止 由 破碎 的 服务 器 端 脚本 引发 的 死 循环 。 这 个 参数 期 
望 得 到 一 个 java.lang.Integer 类 型 的 值 。 如 果 这 个 参数 没有 被 设置 ， 那 么 只 允许 
不 多 余 100 次 重 定 向 。 

http.protocol.allow-circular-redirects : 定义 环形 重 定向 ( 重 定 向 到 
相同 路 径 ) 是 否 被 允许 。HTTP 规 范 在 环形 重 定向 没有 足够 清晰 的 允许 表述 ， 
因此 这 作为 可 选 的 是 可 以 开启 的 。 这 个 参数 期 望 得 到 一 个 java.lang.Boolean 类 
型 的 值 。 如 果 这 个 参数 没有 被 设置 ， 那 么 环形 重 定向 就 不 允许 。 

http.connection-manager.factory-class-name : 定义 了 默认 的 
ClientConnectionManager 实 现 的 类 型 。 这 个 参数 期 望 得 到 一 个 
java.lang.String 类 型 的 值 。 如 果 这 个 参数 没有 被 设置 ， 对 于 每 个 默认 的 将 使 用 
SingleClientConnManager ° 

http.virtual-host :定义 了 在 头 部 信息 Host 中 使 用 的 虚拟 主机 名 称 ， 来 代 
替 物 理 主机 名 称 。 这 个 参数 期 望 得 到 一 个 HttpHost 类 型 的 值 。 如 果 这 个 参数 没 
有 被 设置 ， 那 么 将 会 使 用 目标 主机 的 名 称 或 |P 地 址 。 

http.default-headers :定义 了 每 次 请 求 默 认 发 送 的 头 部 信息 。 这 个 参数 
期 望 得 到 一 个 包含 Header 对 象 的 java.util.Collection 类 型 值 。 

http.default-host : 定义 了 默认 主机 。 如 果 目 标 主机 没有 在 请 求 URI ( 相 
对 URI) 中 明确 指定 ， 那 么 就 使 用 默认 值 。 这 个 参数 期 望 得 到 一 个 HttpHost 类 
型 的 值 S 


5.3 自动 重 定 向 处 理 


Http 
要 用 


Client 处 理 所 有 类 型 的 自动 重 定 向 ， 除 了 那些 由 HTTP 规 范 明令 禁止 的 ， 比 如 需 
户 干预 的 。 参 考 其 它 (状态 码 303) POST 和 PUT 请 求 重 定向 转换 为 由 HTTP 规 


范 需要 的 GET 请 求 。 


沁 而 


5.4 HTTP 和 客户 端 和 执行 上 下 文 


DefaultHttpClient 将 HTTP 请 求 视 为 不 变 的 对 象 ， 也 从 来 不 会 假定 在 请 求 执行 期 间 改 
变 。 相 反 ， 它 创建 了 一 个 原 请 求 对 象 私有 的 可 变 副本 ， 副 本 的 属性 可 以 基于 执行 上 
下 文 来 更 新 。 因 此 ， 如 目标 主键 和 请 求 URI 的 final 类 型 的 请 求 参 数 可 以 在 请 求 执行 
之 后 ， 由 检查 本 地 HTTP 上 下 文 来 决定 。 


DefaultHttpClient httpclient = new DefaultHttpClient(); 

HttpContext localContext = new BasicHttpContext(); 

HttpGet httpget = new HttpGet("http://localhost :8080/"); 

HttpResponse response = httpclient.execute(httpget, localContext 

); 

HttpHost target = (HttpHost) localContext.getAttribute( 
ExecutionContext.HTTP_TARGET_HOST); 

HttpUriRequest req = (HttpUriRequest) localContext.getAttribute( 
ExecutionContext .HTTP_REQUEST ) ; 

System.out.printin("Target host: " + target); 

System.out.printin("Final request URI: " + req.getURI()); 

System.out.printin("Final request method: " + req.getMethod()); 


第 六 章 高 级 主题 


6.1 自 定 义 客 户 端 连接 


在 特定 条 件 下 ， 也 许 需 要 来 定制 HTTP 报 文通 过 线路 传递 ， 越 过 了 可 能 使 用 的 HTTP 
参数 来 处 理 非 标 准 不 兼容 行为 的 方式 。 比 如 ， 对 于 Web 尺 于， 它 可 能 需要 强制 
HttpClient 接 受 格式 错误 的 响应 头 部 信息 ， 来 抢救 报 文 的 内 容 。 


通常 插入 一 个 自 定义 的 报 文 解析 器 的 过 程 或 定制 连接 实现 需要 几 个 步骤 : 


提供 一 个 自 定义 LineParser/LineFormatter 接 口 实现 。 如 果 需 要 ， 实 现 报 文 解析 / 格 
KAGE HE o 


class MyLineParser extends BasicLineParser { 
@Override 
public Header parseHeader ( 
final CharArrayBuffer buffer) throws ParseException { 
try { 
return super.parseHeader (buffer); 
} catch (ParseException ex) { 
// J=#|ParseException# # 
return new BasicHeader("invalid", buffer.toString() ) 


xea 


提 过 一 个 自 定义 的 OperatedClientConnection 实 现 。 和 替换 需要 自 定义 的 默认 请 求 / 响 
应 解 


析 器 ， 请 求 /响应 格式 化 器 。 如 果 需 要 ， 实 现 不 同 的 报 文 写 入 / 读 取代 码 。 


class MyClientConnection extends DefaultClientConnection { 
@Override 
protected HttpMessageParser createResponseParser ( 
final SessionInputBuffer buffer, 
final HttpResponseFactory responseFactory, 
final HttpParams params) { 
return new DefaultResponseParser (buffer, 
new MyLineParser(),responseFactory, params); 


为 了 创建 新 类 的 连接 ， 提 供 一 个 自 定义 的 ClientConnectionOperator 接 口 实现 。 如 
果 需 要 ， 实 现 不 同 的 套 接 字 初始 化 代码 。 


class MyClientConnectionOperator extends 
DefaultClientConnectionOperator { 
public MyClientConnectionOperator ( 
final SchemeRegistry sr) { 
super(sr); 


@Override 

public OperatedClientConnection createConnection() { 
return new MyClientConnection(); 

} 


为 了 创建 新 类 的 连接 操作 ， 提 供 自 定义 的 ClientConnectionManager 接 口 实现 。 


class MyClientConnManager extends SingleClientConnManager { 
public MyClientConnManager ( 
final HttpParams params, 
final SchemeRegistry sr) { 
super(params, sr); 


@Override 
protected ClientConnectionOperator createConnectionOperator ( 
final SchemeRegistry sr) { 
return new MyClientConnectionOperator(sr); 
} 


6.2 有 状态 的 HTTP 连 接 


HTTP 规 范 假设 session 状 态 信 息 通 常 是 以 HTTP cookie 格 式 葡 入 在 HTTP 报 文中 的 ， 
因此 HTTP 连 接 通 常 是 无 状态 的 ， 这 个 假设 在 现实 生活 中 通常 是 不 对 的 。 也 有 一 些 
情况 ， 当 HTTP 连 接 使 用 特定 的 用 户 标 识 或 特定 的 安全 上 下 文 来 创建 时 ， 因 此 不 能 
和 其 它 用 户 共享 ， 只 能 由 该 用 户 重 用 。 这 样 的 有 状态 的 HTTP 连 接 的 示例 就 是 NTLM 
认证 连接 和 使 用 客户 端 证 书 认证 的 SSL 连 接 。 


6.2.1 用 户 令 牌 处 理 器 


HttpClient 依 赖 UserTokenHandler 接 口 来 决定 给 定 的 执行 上 下 文 是 否 是 用 户 指定 
的 。 如 果 这 个 上 下 文 是 用 户 指定 的 或 者 如 果 上 下 文 没有 包含 任何 资源 或 关于 当前 用 
户 指定 详情 而 是 null， 令 牌 对 象 由 这 个 处 理 器 返回 ， 期 望 唯一 地 标识 当前 的 用 户 。 
用 户 令 牌 将 被 用 来 保证 用 户 指定 资源 不 会 和 其 它 用 户 来 共享 或 重用 。 


如 果 它 可 以 从 给 定 的 执行 上 下 文中 来 获得 ，UserTokenHandler 接 口 的 默认 实现 是 使 
用 主 类 的 一 个 实例 来 代表 HTTP 连 接 的 状态 对 象 。UserTokenHandler 将 会 使 用 基于 
如 NTLM 或 开局 的 客户 端 认 证 SSL 会 话 认 证 模式 的 用 户 的 主 连接 。 如 果 二 者 都 不 可 
用 ， 那 么 就 不 会 返回 令 牌 。 


如 果 默 认 的 不 能 满足 它们 的 需要 ， 用 户 可 以 提供 一 个 自 定 义 的 实现 : 


DefaultHttpClient httpclient = new DefaultHttpClient(); 
httpclient.setUserTokenHandler(new UserTokenHandler() { 
public Object getUserToken(HttpContext context) { 
return context.getAttribute("my-token"); 


} 
}); 


6.2.2 用 户 令 牌 和 执行 上 下 文 


在 HTTP 请 求 执行 的 过 程 中 ，HttpClient 添 加 了 下 列 和 用 户 标识 相关 的 对 象 到 执行 上 
下 文中 : 


http.user-token : 对 象 实例 代表 站 实 的 用 户 标识 ， 通 常 期 望 Principle 接 口 的 实 
例 o 


我 们 可 以 在 请 求 被 执行 后 ， 通 过 检查 本 地 HTTP 上 下 文 的 内 容 ， 发 现 是 否 用 于 执行 
请 求 的 连接 是 有 状态 的 。 


DefaultHttpClient httpclient = new DefaultHttpClient(); 
HttpContext localContext = new BasicHttpContext(); 
HttpGet httpget = new HttpGet("http://localhost:8080/"); 
HttpResponse response = httpclient.execute(httpget, localContext 
); 
HttpEntity entity = response.getEntity(); 
if (entity != null) { 

entity.consumeContent(); 
} 


Object userToken = localContext.getAttribute(ClientContext .USER_ 
TOKEN); 
System.out.println(userToken) ; 


6.2.2.1 持久 化 有 状态 的 连接 

请 注意 带 有 状态 对 象 的 持久 化 连接 仅 当 请 求 被 执行 时 ， 相 同 状 态 对 象 被 绑 定 到 执行 
上 下 文 时 可 以 被 重用 。 所 以 ， 保 证 相同 上 下 文 重用 于 执行 随后 的 相同 用 户 ， 或 用 户 
令 牌 绑 定 到 之 前 请 求 执行 上 下 文 的 HTTP 请 求 是 很 重要 的 。 


DefaultHttpClient httpclient = new DefaultHttpClient(); 
HttpContext localContext1 = new BasicHttpContext(); 
HttpGet httpgeti = new HttpGet("http://localhost:8080/"); 
HttpResponse responsei = httpclient.execute(httpgeti, localConte 
XED) 
HttpEntity entity1 = response1.getEntity(); 
if (entity1 != null) { 
entity1.consumeContent(); 
} 
Principal principal = (Principal) localContext1.getAttribute( 
ClientContext .USER_TOKEN) ; 
HttpContext localContext2 = new BasicHttpContext(); 
localContext2.setAttribute(ClientContext.USER_TOKEN, principal); 
HttpGet httpget2 = new HttpGet("http://localhost:8080/"); 
HttpResponse response2 = httpclient.execute(httpget2, localConte 
B20 
HttpEntity entity2 = response2.getEntity(); 
if (entity2 != null) { 
entity2.consumeContent(); 
} 
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来 源 : MyBatis 中 文 文档 


简介 


什么 是 MyBatis ? 


MyBatis 是 支持 定制 化 SQL、 存 储 过 程 以 及 高 级 映射 的 优秀 的 持久 层 框 架 。 
MyBatis 避免 了 几乎 所 有 的 JDBC 代码 和 手动 设置 参数 以 及 获取 结果 集 。MyBatis 
可 以 对 配置 和 原生 Map 使 用 简单 的 XML 或 注解 ， 将 接口 和 Java 的 POJOs(Plain 
Old Java Objects, 普 通 的 Java 对 象 ) 映 射 成 数据 库 中 的 记录 。 


帮助 改进 文档 ..， 
不 管 你 以 何 种 方式 发 现 了 文档 的 不 足 ， 或 是 丢失 对 某 一 特性 的 描述 ， 那 么 你 能 做 的 
最 好 的 事情 英 过 于 去 研究 它 并 把 文档 写 出 来 。 


该 文档 xdoc 格式 的 源码 文件 可 通过 项 目的 Git 代码 库 来 获取 。Fork 该 源码 库 ， 做 
出 更 新 ， 然 后 提交 一 个 pull request 吧 。 


你 将 成 为 本 文档 的 最 佳作 者 ，MyBatis 的 用 户 定 会 过 来 查阅 的 。 


当前 的 国际 化 版 本 
MyBatis 的 其 他 语言 版 本 : 


e English 
e Espa?ol 
e 日 本 语 
e 2??? 

e 简体 中 文 


你 想 使 用 本 地 语言 来 了 解 MyBatis 吗 ? 那 就 将 它 翻译 成 你 的 母语 并 提供 给 我 们 吧 | 


AT] 
安装 


要 使 用 MyBatis ， 只 需 将 mybatis-x.x.x.jar 文件 置 于 classpath 中 即 可 。 
如 果 使 用 Maven 来 构建 项 目 ， 则 需 将 下 面 的 dependency 代码 置 于 pom.xml 文件 
中 : 


<dependency> 
<groupId>org.mybatis</groupId> 
<artifactId>mybatis</artifactId> 
<version>x.x.x</version> 
</dependency> 


从 XML 中 构建 SqlSessionFactory 


每 个 基于 MyBatis 的 应 用 都 是 以 一 个 SqlSessionFactory 的 实例 为 中 心 的 。 
SqlSessionFactory 的 实例 可 以 通过 SqlSessionFactoryBuilder 获得 。 而 
SqlSessionFactoryBuilder 则 可 以 从 XML 配置 文件 或 一 个 预先 定制 的 


Configuration 的 实例 构建 出 SqlSessionFactory 的 实例 。 


从 XML 文件 中 构建 SqlSessionFactory 的 实例 非常 简单 ， 建 议 使 用 类 路 径 下 的 资 
源 文件 进行 配置 。 但 是 也 可 以 使 用 任意 的 输入 流 (InputStream) 实 例 ， 包 括 字符 串 形 
式 的 文件 路 径 或 者 fle:// 的 URL 形式 的 文件 路 径 来 配置 。MyBatis 包含 一 个 名 叫 
Resources 的 工具 类 ， 它 包含 一 些 实用 方法 ， 可 使 从 classpath 或 其 他 位 置 加 载 资 
源 文 件 更 加 容易 。 


String resource = "org/mybatis/example/mybatis-config. xml"; 
InputStream inputStream = Resources.getResourceAsStream(resource 
); 

sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputSt 
ream); 


XML 配置 文件 (configuration XML) 中 包含 了 对 MyBatis 系 opiates > 2 
获取 数据 库 连 接 实例 的 数据 源 (DataSource) #7 RFF UH Fede FH o 事务 管 
(TransactionManager) 。 XML 配置 文件 的 详细 内 容 后 a 里 先 

一 个 简单 的 示例 : 


<?xml version="1.0" encoding="UTF-8" ?> 
<!DOCTYPE configuration 
PUBLIC "-//mybatis.org//DTD Config 3.0//EN" 
"http://mybatis.org/dtd/mybatis-3-config.dtd"> 
<configuration> 
<environments default="development"> 
<environment id="development"> 
<transactionManager type="JDBC"/> 
<dataSource type="POOLED"> 
<property name="driver" value="${driver}"/> 
<property name="url" value="${url}"/> 
<property name="username" value="${username}"/> 
<property name="password" value="${password}"/> 
</dataSource> 
</environment> 
</environments> 
<mappers> 
<mapper resource="org/mybatis/example/BlogMapper . xm1"/> 
</mappers> 
</configuration> 


然 ， 还 有 很 多 可 以 在 XML 文件 中 进行 配置 ， 上 面 的 示例 指出 的 则 是 最 关键 的 部 

。 要 注意 XML 头 部 的 声明 ， 用 来 验证 XML 文档 正确 性 。environment 元 素 体 中 
含 了 事务 管理 和 连接 池 的 配置 。mappers 元 素 则 是 包含 一 组 mapper 映射 器 (这 
mapper 的 XML 文件 包含 了 SQL 代码 和 映射 定义 信息 ) 。 


fey 


不 使 用 XML 构建 SqlSessionFactory 


如 果 你 更 愿意 直接 从 Java 程序 而 不 是 XML 文件 中 创建 configuration， 或 者 创建 你 
自己 的 configuration 构建 器 ，MyBatis 也 提供 了 完整 的 配置 类 ， 提 供 所 有 和 XML 
文件 相同 功能 的 配置 项 。 


DataSource dataSource = BlogDataSourceFactory.getBlogDataSource( 


); 


TransactionFactory transactionFactory = new JdbcTransactionFacto 


ry(); 
Environment environment = new Environment("development", transac 


tionFactory, dataSource); 
Configuration configuration = new Configuration(environment ); 


configuration.addMapper(BlogMapper.class); 
SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuild 


er().build(configuration) ; 


注意 该 例 中 ，configuration 添加 了 一 个 映射 器 类 (mapper class) ° RA A Re 
Java 类 ， 它 们 包含 SQL 映射 语句 的 注解 从 而 避免 了 XML 文件 的 依赖 。 不 过 ， 由 
于 Java 注解 的 一 些 限制 加 之 某 些 MyBatis 映射 的 复杂 性 ，XML 映射 对 于 大 多 数 高 
级 映射 (比如: HA Join RA) 来 说 仍然 是 必须 的 。 有 鉴于 此 ， 如 果 存 在 一 个 对 等 


的 XML 配置 文件 的 话 ，MyBatis 会 自动 查找 并 加 载 它 (这 种 情况 下 ， 
BlogMapper.xml 将 会 基于 类 路 径 和 BlogMapper.class 的 类 名 被 加 载 进来 ) 。 具 体 
细节 稍 后 讨论 。 


从 SqlSessionFactory 中 获取 SqlSession 


既然 有 了 SqlSessionFactory ， 顾 名 思 义 ， 我 们 就 可 以 从 中 获得 SqlSession 的 实 
例 了 。SqlSession 完全 包含 了 面向 数据 库 执行 SQL 命令 所 需 的 所 有 方法 。 你 可 以 
通过 SqlSession 实例 来 直接 执行 已 映射 的 SQL 语句 。 例 如: 


SqlSession session = sqlSessionFactory.openSession(); 


try { 
Blog blog = (Blog) session.selectOne("org.mybatis.example.Blog 


Mapper.selectBlog", 101); 
} finally { 
session.close(); 


} 


诚然 这 种 方式 能 够 正常 工作 ， 并 且 对 于 使 用 中 版 本 MyBatis 的 用 户 来 说 也 比较 熟 
悉 ， 不 过 现在 有 了 一 种 更 直 白 的 方式 。 使 用 对 于 给 定语 多 能 够 合理 描述 参数 和 返回 
值 的 接口 (比如 说 BlogMapper.class) ， 你 现在 不 但 可 以 执行 更 清晰 和 类 型 安全 的 
代码 ， 而 且 还 不 用 担心 易 错 的 字符 串 字 面值 以 及 强制 类 型 转换 。 


例如 : 


SqlSession session = sqlSessionFactory.openSession(); 


try { 
BlogMapper mapper = session.getMapper(BlogMapper.class); 
Blog blog = mapper.selectBlog(101); 

} finally { 
session.close(); 


} 
现在 我 们 来 探究 一 下 这 里 到 底 是 怎么 执行 的 。 


探究 已 映射 的 SQL 语句 


现在 ， 或 许 你 很 想 知 道 SqlSession 和 Mapper 到 底 执 行 了 什么 操作 ， 而 SQL 语句 
映射 是 个 相当 大 的 话题 ， 可 能 会 占 去 文档 的 大 部 分 篇 幅 。 不 过 为 了 让 你 能 够 了 解 个 
大 概 ， 这 里 会 给 出 几 个 例子 。 


在 上 面 提 到 的 两 个 例子 中 ， 一 个 语句 应 该 是 通过 XML 定义 ， 而 另外 一 个 则 是 通过 
注解 定义 。 先 看 XML 定义 这 个 ， 事 实 上 MyBatis 提供 的 全 部 特性 可 以 利用 基于 
XML 的 映射 语言 来 实现 ， 这 使 得 MyBatis 在 过 去 的 数 年 间 得 以 流行 。 如 果 你 以 前 
用 过 MyBatis， 这 个 概念 应 该 会 比较 熟悉 。 不 过 XML 映射 文件 已 经 有 了 很 多 的 改 
进 ， 随 着 文档 的 进行 会 愈 发 清晰 。 这 里 给 出 一 个 基于 XML 映射 语句 的 示例 ， 它 应 
该 可 以 满足 上 述 示 例 中 SqlSession 的 调用 。 


<?xml version="1.0" encoding="UTF-8" ?> 
<!DOCTYPE mapper 
PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" 
"http://mybatis.org/dtd/mybatis-3-mapper.dtd"> 
<mapper namespace="org.mybatis.example.BlogMapper"> 
<select id="SelectBlog" resultType="Blog"> 
select * from Blog where id = #{id} 
</select> 
</mapper> 


对 于 这 个 简单 的 例子 来 说 似乎 有 点 小 题 大 做 了 ， 但 实际 上 它 是 非常 轻 量 级 的 。 在 一 
个 XML 映射 文件 中 ， 你 想 定义 多 少 个 映射 语句 都 是 可 以 的 ， 这 样 下 来 ，XML 头 部 
和 文档 类 型 声明 占 去 的 部 分 就 显得 微不足道 了 。 文 件 的 剩余 部 分 具有 很 好 的 自 解释 
性 。 在 命名 空间 "com.mybatis.example.BlogMapper 中 定义 了 一 个 名 

为 “selectBlog "的 映射 语 名 ， 这 样 它 就 允许 你 使 用 指定 的 完全 限定 

名 “org.mybatis.example.BlogMapper.selectBlog” 来 调用 映射 语句 ， 就 像 上 面 的 例子 
中 做 的 那样 : 


Blog blog = (Blog) session.selectOne("org.mybatis.example.BlogMa 
pper.selectBlog", 101); 


你 可 能 注意 到 这 和 使 用 完全 限定 名 调用 Java 对 象 的 方法 是 相似 的 ， 之 所 以 这 样 做 
是 有 原因 的 。 这 个 命名 可 以 直接 映射 到 在 命名 空间 中 同名 的 Mapper 类 ， 并 在 已 映 
射 的 select 语 名 中 的 名 字 、 参 数 和 返回 类 型 匹配 成 方法 。 这 样 你 就 可 以 向 上 面 那样 
很 容易 地 调用 这 个 对 应 Mapper 接口 的 方法 。 不 过 让 我 们 再 看 一 遍 下 面 的 例子 : 


BlogMapper mapper = session.getMapper (BlogMapper.class); 
Blog blog = mapper .selectBlog(101); 


第 二 种 方法 有 很 多 优势 ， 首 先 它 不 是 基于 字符 串 常量 的 ， 就 会 更 安全 ; HK wR 
你 的 IDE 有 代码 补 全 功能 ， 那 么 你 可 以 在 有 了 已 映射 SQL 语句 的 基础 之 上 利用 这 


个 功能 。 


提示 命名 空间 的 一 点 注释 

命名 空间 (Namespaces) 在 之 前 版 本 的 MyBatis 中 是 可 选 的 ， 容 易 引 起 混淆 因此 
是 没有 益处 的 。 现 在 的 命名 空间 则 是 必须 的 ， 目 的 是 希望 能 比 只 是 简单 的 使 用 更 长 
的 完全 限定 名 来 区 分 语句 更 进一步 。 


命名 空间 使 得 你 所 见 到 的 接口 绑 定 成 为 可 能 ， 尽 管 你 觉得 这 些 东西 未 必用 得 上 ， 你 
还 是 应 该 遵循 这 里 的 规定 以 防 哪 天 你 改变 了 主意 。 出 于 长 远 考虑 ， 使 用 命名 空间 ， 
并 将 它 置 于 合适 的 Java 包 命 名 空间 之 下 ， 你 将 拥有 一 份 更 加 整洁 的 代码 并 提高 了 
MyBatis 的 可 用 性 。 


命名 解析 : 为 了 减少 输入 量 ，MyBatis 对 所 有 的 命名 配置 元 素 ( 包括 语句 ， 结 果 映 
St BBE) 使 用 了 如 下 的 命名 解析 规则 。 


e 完全 限定 名 (上 比如 “com.mypackage.MyMapper.selectAllThings”) 将 被 直接 查 
找 并 且 找 到 即 用 。 

o 短 名 称 (比如 “selectAlIThings”) 如 果 全 局 唯一 也 可 以 作为 一 个 单独 的 引用 。 如 
果 不 唯 一 ， 有 两 个 或 两 个 以 上 的 相同 名 称 ( 比如 “com.foo.selectAllThings 
"和 “com.bar.selectAllThings”) ， 那 么 使 用 时 就 会 收 到 错误 报告 说 短 名 称 是 不 
唯一 的 ， 这 种 情况 下 就 必须 使 用 完全 限定 名 。 


对 于 像 BlogMapper 这 样 的 映射 器 类 (Mapper class) 来 说 ， 还 有 另 一 招来 处 理 。 
它们 的 映射 的 语句 可 以 不 需要 用 XML 来 做 ， 取 而 代 之 的 是 可 以 使 用 Java 注解 。 比 
go> Emi) XML 示例 可 被 替换 如 下 : 


package org.mybatis.example; 

public interface BlogMapper { 
@Select("SELECT * FROM blog WHERE id = #{id}") 
Blog selectBlog(int id); 

} 


对 于 简单 语句 来 说 ， 注 解 使 代码 显得 更 加 简洁 ， 然 而 Java 注解 对 于 稍微 复杂 的 语 
名 就 会 力不从心 并 且 会 显得 更 加 混乱 。 因 此 ， 如 果 你 需要 做 很 复杂 的 事情 ， 那 么 最 
好 使 用 XML 来 映射 语 名 j 


选择 何 种 方式 以 及 映射 语句 的 定义 的 一 致 性 对 你 来 说 有 多 重要 这 
你 的 团队 。 换 名 话说， 永远 不 要 拘泥 于 一 种 方式 ， 你 可 以 很 轻松 
XML 的 语句 映射 方式 间 自 由 移植 和 切换 。 


些 完全 取决 于 你 和 
的 在 基于 注解 和 


范围 (Scope) 和 生命 周期 


理解 我 们 目前 已 经 讨论 过 的 不 同 范围 和 生命 周期 类 是 至 关 重 要 的 ， 因 为 错误 的 使 用 
会 导致 非常 严重 的 并 发 问题 。 


提示 对 象 生 命 周 期 和 依赖 注入 框架 


依赖 注入 框架 可 以 创建 线程 安全 的 、 基 于 事务 的 SqlSession 和 映射 器 (mapper) 
并 将 它们 直接 注入 到 你 的 bean 中 ， 因 此 可 以 直接 忽略 它们 的 生命 周期 。 如 果 对 如 
何 通过 依赖 注入 框架 来 使 用 MyBatis 感 兴趣 可 以 研究 一 下 MyBatis-Spring 或 
MyBatis-Guice 两 个 子 项 目 。 


SqlSessionFactoryBuilder 


这 个 类 可 以 被 实例 化 、 使 用 和 丢弃 ， 一 旦 创建 了 SqlSessionFactory ， 就 不 再 需要 
它 了 。 因 ar a a PE 实例 的 最 佳 范围 是 方法 范围 (也 就 是 局 部 方 
法 变量 ) 。 你 可 以 重用 SqlSessionFactoryBuilder 来 创建 多 个 SqlSessionFactory 
实例 ， 但 是 最 好 还 是 不 要 让 其 一 直 存 在 以 保证 所 有 的 XML 解析 资源 开放 给 更 重要 
的 事情 。 


SqlSessionFactory 


SqlSessionFactory 一 旦 被 创建 就 应 该 在 应 用 的 运行 期 间 一 直 存 在 ， 没 有 任何 理由 
对 它 进 行 清 除 或 重建 。 。 使 用 SqlSessionFactory 的 最 佳 实践 是 在 应 用 运行 期 间 不 要 
重复 创建 多 次 ， 多 次 重建 SqlSessionFactory 被 视 为 一 Ab RB ‘RIA (bad 
smell) ” Ja 因此 SqlSessionFactory 的 最 佳 范围 是 应 用 范围 。 有 很 多 方法 可 以 做 

到 ， 最 简单 的 就 是 使 用 单 例 模式 或 者 静态 单 例 模式 。 


SqlSession 


每 个 线程 都 应 该 有 它 自己 的 SqlSession 实例 。SqlSession 的 实例 不 是 线程 安全 
的 ， 因 此 是 不 能 被 共享 的 ， 所 以 它 的 最 佳 的 范围 是 请 求 或 方法 范围 。 绝 对 不 能 将 
oon 实例 的 引用 放 在 一 个 类 的 静态 域 ， 蔚 至 一 个 类 的 实例 变量 也 不 和 if 。 也 绝 

能 将 SqlSession 实例 的 引用 放 在 任何 类 型 的 管理 范围 中 ， 比 如 Serlvet 架构 中 的 
HitpSesslon 。 如 果 你 现在 正在 使 用 一 种 Web 框架 ， 要 考虑 SqlSession 放 在 一 个 
和 HTTP 请 求 对 象 相似 的 范围 中 。 换 名 话说 ， 每 次 收 到 的 HTTP 请 求 ， 就 可 以 打开 
一 个 SqlSession， 返 回 一 个 响应 ， 就 关闭 它 。 这 个 关闭 操作 是 很 重要 的 ， 你 应 该 把 
这 个 关闭 操作 放 到 finally 块 中 以 确保 每 次 都 能 执行 关闭 。 下 面 的 示例 就 是 一 个 确保 
SqlSession 关闭 的 标准 模式 : 


SqlSession session = sqlSessionFactory.openSession(); 


try { 
// do work 


} finally { 
session.close(); 


} 


在 你 的 所 有 的 代码 中 一 致 性 地 使 用 这 种 模式 来 保证 所 有 数据 库 资 源 都 能 被 正确 地 关 
闭 。 


映射 器 实例 (Mapper Instances ) 


映射 器 创建 用 来 绑 定 映射 语 名 的 接口 。 上 映射 器 接口 的 实例 是 从 SqlSession 中 获 
得 的 。 pie! 面 讲 ， 映 射 器 实例 的 最 大 范围 是 和 SqlSession 相 同 的 ， 因为 
EMRE SqlSession 里 被 请 求 的 。 尽 管 如 此 ， 了 映射 器 实例 的 最 佳 范围 是 方法 范 
围 。 也 就 是 说 ， 了 映射 器 实例 应 该 在 调用 它们 的 方法 中 被 请 求 ， 用 过 之 后 即 可 废弃 。 
需要 显 式 地 关闭 映射 器 实例 ， 和 个 请 求 范围 (request scope) 保持 映射 
器 实例 也 不 会 有 什么 问题 ， 但 是 尔 会 发 现 ， 像 SqlSession 一 样 ， 在 这 个 范围 
上 管理 太 多 的 资源 的 话 会 难于 控制 > i 以 要 保持 简 简单 ， 最 好 把 映射 器 放 在 方法 范围 
(method scope) 内 。 下 面 的 示例 就 展示 了 这 个 实践 : 


SqlSession session = sqlSessionFactory.openSession(); 

try { 
BlogMapper mapper = session.getMapper(BlogMapper.class); 
// do work 

} finally { 
session.close(); 


} 


ATT 
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XML 映射 配置 文件 


MyBatis 的 配置 文件 包含 了 影响 Wan 行为 其 深 的 设置 (settings ) 和 属性 
(properties) 信息 。 文 档 的 ] 顶层 结构 如 下 


e configuration 配置 
o properties 属性 
settings 设置 
typeAliases 类 型 命名 
typeHandlers 类 型 处 理 器 
objectFactory 对 象 工厂 
plugins 插件 
environments 环境 
= environment 环境 变量 
= transactionManager 事务 管理 器 
= dataSource 数据 产 
databaseldProvider 数据 库 厂 商标 识 
mappers 映射 器 


O O O O 0 0 


O O 


properties 


这 些 属 且 可 动态 替换 的 ， 既 可 以 在 典型 的 Java 属性 文件 中 配 
置 ， 亦 可 通过 properties 元 素 的 子 元 素来 传递 。 例 如 : 


<properties resource="org/mybatis/example/config.properties"> 
<property name="username" value="dev_user"/> 
<property name="password" value="F2Fa3!33TYyg"/> 
</properties> 


其 中 的 属性 就 可 以 在 整个 配置 文件 中 使 用 来 蔡 换 需 要 动态 配置 的 属性 值 。 比 如 : 


<dataSource type="POOLED"> 
<property name="driver" value="${driver}"/> 
<property name="url" value="${url}"/> 
<property name="username" value="${username}"/> 
<property name="password" value="${password}"/> 
</dataSource> 


这 个 例子 中 的 username 和 password 7 2 properties 元 素 中 设置 的 相应 HB RG 
换 。 driver 和 url 属性 将 会 由 config.properties 文件 中 对 应 的 值 来 替换 。 这 样 就 为 
配置 提供 了 诸多 灵活 选择 。 


属性 也 可 以 被 传递 到 SqlSessionBuilder.build() 方 法 中 。 例 如 : 


SqlSessionFactory factory = sqlSessionFactoryBuilder.build(reade 
r, props); 


VE nok OW ake 


SqlSessionFactory factory = sqlSessionFactoryBuilder.build(reade 
r, environment, props); 


如 果 属 性 在 不 只 一 个 地 方 进行 了 配置 ， 那 么 MyBatis 将 按照 下 面 的 顺序 来 加 载 : 


e 在 properties 元 素 体 内 指定 的 属性 首先 被 读 取 。 

e 然后 根据 properties 元 素 中 的 resource 属性 读 取 类 路 径 下 属性 文件 或 根据 url 
属性 指定 的 路 径 读 取 属性 文件 ， 并 和 窗 盖 已 读 取 的 同名 属性 。 

o 最 后 读 取 作为 方法 参数 传递 的 属性 ， 并 和 窗 盖 已 读 取 的 同名 属性 。 


因此 ， 通 过 方法 参数 传递 的 属性 具有 最 高 优先 级 ，resource/url 属性 中 指定 的 配置 
文件 次 之 ， 最 低 优先 级 的 是 properties 属性 中 指定 的 属性 。 


settings 


这 是 MyBatis 中 极为 重要 的 调整 设置 ， 它 们 会 改变 MyBatis 的 运行 时 行为 。 下 表 描 
述 了 设置 中 各 项 的 意图 、 默 认 值 等 。 


设置 参数 描述 有 效 值 


该 配置 影响 的 所 有 
cacheEnabled 映射 器 中 配置 的 缓 true | false 
存 的 全 局 开关 。 


延迟 加 载 的 全 局 开 

关 。 当 开局 时 ， 所 

有 关联 对 象 都 会 延 
lazyLoadingEnabled true | false 

置 fetchType 属 

性 来 覆盖 该 项 的 开 

关 状 态 。 


当局 用 时 ， 对 任意 
延迟 属性 的 调用 会 
. 使 带 有 延迟 加 载 属 
aggressiveLazyLoading 性 的 对 象 完整 加 true | false 
载 ; 反之 ， 每 种 属 
性 将 会 按 需 加 载 。 
是 否 允 许 单一 语句 
multipleResultSetsEnabled 返回 多 结果 集 ( 需 true |false 
要 兼容 驱动 ) 。 


useColumnLabel 


useGeneratedKeys 


autoMappingBehavior 


defaultExecutorType 


defaultStatementTimeout 


defaultFetchSize 


使 用 列 标签 代替 列 
名 。 不 同 的 驱动 在 
这 方面 会 有 不 同 的 
表现 ， 具体 可 参考 
相关 驱动 文档 或 通 
过 测试 这 两 种 不 同 
的 模式 来 观察 所 用 
驱动 的 结果 。 


允许 JDBC 支持 自 
动 生 成 主键 ， 需 要 
驱动 兼容 。 如 果 设 
置 为 true 则 这 个 设 
置 强制 使 用 自动 生 
成 主键 ， 尽 管 一 些 
驱动 不 能 兼容 但 仍 
可 正常 工作 (比如 
Derby) 。 


指定 MyBatis 应 如 
何 自动 映射 列 到 字 
段 或 属性 。NONE 
表示 取消 自动 映 
射 ; PARTIAL 只 会 
自动 映射 没有 定义 
MBAR HORA HY 
结果 集 。 FULL 会 
自动 映射 任意 复杂 
的 结果 集 (无 论 是 
GRE) © 


配置 默认 的 执行 
器 。SIMPLE 就 是 
普通 的 执行 器 ; 
REUSE hir š a 
重用 预 处 理 语句 
(prepared 
statements) ; 
BATCH 44r & 4% 
重用 语句 并 执行 批 
量 更 新 。 


设置 超时 时 间 ， 它 
决定 驱动 等 待 数 据 
库 响应 的 秒 数 。 


Sets the driver a 
hint as to control 
fetching size for 
return results. This 


true | false 


true | false 


NONE, PARTIAL, FULL 


SIMPLE REUSE 
BATCH 


Any positive integer 


Any positive integer 


safeRowBoundsEnabled 


mapUnderscore ToCamelCase 


localCacheScope 


jdbcTypeForNull 


lazyLoadTriggerMethods 


parameter value 
can be override by 
a query setting. 


允许 在 齿 套 语句 中 
使 用 分 页 
(RowBounds) 。 


是 否 开启 自动 驼峰 
命名 规则 (camel 
case) 上 映射， 即 从 
经 典 数 据 库 列 名 
A_COLUMN 到 经 
$ Java 属性 名 
aColumn 的 类 似 映 
射 。 


MyBatis 利用 本 地 
缓存 机 制 (Local 
Cache) 防止 循环 
引用 (circular 
references) 和 加 
速 重复 媒 套 查询 。 
默认 值 为 
SESSION， 这 种 
情况 下 会 缓存 一 个 
会 话 中 执行 的 所 有 
EW o Bi BA 
STATEMENT > #& 
地 会 话 仅 用 在 语句 
执行 上 ， 对 相同 
SqlSession 的 不 同 
调用 将 不 会 共享 数 
T 


当 没 有 为 参数 提供 
特定 的 JDBC 类 型 
时 ， 为 空 值 指定 
JDBC 类 型 。 Hue 
驱动 需要 指定 列 的 
JDBC 类 型 ， 多 数 
情况 直接 用 一 般 类 
型 即 可 ， 比 如 
NULL ` VARCHAR 
或 OTHER ° 


指定 哪个 对 象 的 方 
法 触发 一 次 延迟 加 
载 。 


true | false 


true | false 


SESSION | 
STATEMENT 


JdbcType enumeration. 
Most common are: 
NULL, VARCHAR and 
OTHER 


A method name list 
separated by commas 


defaultScriptingLanguage 


callSettersOnNulls 


logPrefix 


loglmpl 


proxyFactory 


vfsImpl 


指定 动态 SQL 生 
成 的 RUH = 2 


指定 当 结 果 集 中 值 
A null 的 时 候 是 否 
调用 映射 对 象 的 
setter (map 对 象 
时 为 put) 方法 ， 
这 对 于 有 
Map.keySet() 依赖 
或 null 值 初始 化 的 
时 候 是 有 用 的 。 注 
意 基本 类 型 (int、 
boolean 等 ) 是 不 
能 设置 成 null 的 。 


指定 MyBatis 增加 
到 日 志 名 称 的 前 


A o 


指定 MyBatis 所 用 
日 志 的 具体 实现 ， 
未 指定 时 将 自动 查 
找 。 


指定 Mybatis 创建 
具有 延迟 加 载 能 
的 对 象 所 用 到 的 代 
理工 具 。 


Specifies VFS 
implementations 


一 个 配置 完整 的 settings 元 素 的 示例 如 下 : 


Atype alias or fully 
qualified class name. 


true | false 


Any String 


SLF4J | LOG44 | 
LOG4J2 | 
JDK_LOGGING | 
COMMONS _LOGGING 
| STDOUT_LOGGING | 
NO_LOGGING 


CGLIB | JAVASSIST 


Fully qualified class 
names of custom VFS 
implementation 
separated by commas. 


<settings> 


<setting 
<setting 
<setting 
<setting 
<setting 
<setting 
<setting 
<setting 
<setting 


name="cacheEnabled" value="true"/> 
name="lazyLoadingEnabled" value="true"/> 
name="multipleResultSetsEnabled" value="true"/> 
name="useColumnLabel" value="true"/> 
name="useGeneratedKeys" value="false"/> 
name="autoMappingBehavior" value="PARTIAL"/> 
name="defaultExecutorType" value="SIMPLE"/> 
name="defaultStatementTimeout" value="25"/> 
name="defaultFetchSize" value="100"/> 


<setting name="safeRowBoundsEnabled" value="false"/> 
<setting name="mapUnderscoreToCamelCase" value="false"/> 
<setting name="localCacheScope" value="SESSION"/> 
<setting name="jdbcTypeForNull" value="OTHER"/> 
<setting name="lazyLoadTriggerMethods" value="equals, clone, has 
hCode, toString"/> 
</settings> 
typeAliases 


类 型 别名 是 为 Java 类 型 设置 一 个 短 的 名 字 。 它 只 和 XML 配置 有 关 ， 存 在 的 意义 仅 
在 于 用 来 减少 类 完全 限定 名 的 宛 余 。 例 如 : 


<typeAliases> 
<typeAlias alias="Author" type="domain.blog.Author"/> 
<typeAlias alias="Blog" type="domain.blog.Blog"/> 
<typeAlias alias="Comment" type="domain.blog.Comment"/> 
<typeAlias alias="Post" type="domain.blog.Post"/> 
<typeAlias alias="Section" type="domain.blog.Section"/> 
<typeAlias alias="Tag" type="domain.blog.Tag"/> 


</typeAliases> 


当 这 样 配置 时 ， Blog 可 以 用 在 任何 使 用 domain.blog.Blog 的 地 方 。 
也 可 以 指定 一 个 包 名 ，MyBatis 会 在 包 名 下 面 搜索 需要 的 Java Bean > rite: 


<typeAliases> 
<package name="domain.blog"/> 
</typeAliases> 


每 一 个 在 包 domain.blog 中 的 Java Bean， 在 没有 注解 的 情况 下 ， 会 使 用 Bean 
的 首 字母 小 写 的 非 限定 类 名 来 作为 它 的 别名 。 比如 domain.blog.Author 的 别 
名 为 author > 若 有 注解 ， 则 别名 为 其 注解 值 。 看 下 面 的 例子 : 


@Alias("author" ) 
public class Author { 


} 


已 经 为 许多 常见 的 Java 类 型 内 建 了 相应 的 类 型 别名 。 它 们 都 是 大 小 写 不 敏感 的 ， 
需要 注意 的 是 由 基本 类 型 名 称 重复 导致 的 特殊 处 理 。 


_integer 
_ double 
_ float 

_ boolean 
string 
byte 

long 
short 

int 
integer 
double 
float 
boolean 
date 
decimal 
bigdecimal 
object 
map 
hashmap 
list 
arraylist 
collection 


iterator 


typeHandlers 


double 
float 
boolean 
String 
Byte 

Long 
Short 
Integer 
Integer 
Double 
Float 
Boolean 
Date 
BigDecimal 
BigDecimal 
Object 
Map 
HashMap 
List 
ArrayList 
Collection 


Iterator 


映射 的 类 型 


无 论 是 MyBatis # fi 22278 4) (PreparedStatement) 中 设置 一 个 参数 时 ， 还 是 从 
结果 集中 取出 一 个 值 时 ， 都 会 用 类 型 处 理 器 将 获取 的 值 以 合适 的 方式 转换 成 Java 
类 型 。 下 表 描 述 了 一 些 默认 的 类 型 处 理 器 。 


RA ABS 


BooleanTypeHandler 


ByteTypeHandler 


ShortTypeHandler 


IntegerTypeHandler 


LongTypeHandler 


FloatTypeHandler 


DoubleTypeHandler 


BigDecimalTypeHandler 


StringTypeHandler 


ClobTypeHandler 


NStringTypeHandler 
NCLobTypeHandler 


ByteArrayTypeHandler 


BlobTypeHandler 


Java 类 型 


java. lang 
boolean 


java.lang. 


byte 


java.lang 
short 


java.lang. 


TUANE 


java. lang. 


long 


java. lang. 


float 


java. lang. 


double 


java.math. 


java.lang 


java. lang 


java.lang 


java. lang 


byte[] 


byte[] 


.Boolean , 


Byte , 


Shonta, 


Integer , 


Long , 


Float , 


Double , 


BigDecimal 


ose as ai | 


SO 


.String 


.String 


JDBC 类 型 


数据 库 兼 容 的 
BOOLEAN 
数据 库 兼 容 的 
NUMERIC 或 
BYTE 


数据 库 兼 容 的 
NUMERIC 或 
SHORT INTEGER 


数据 库 兼 容 的 
NUMERIC 或 
INTEGER 


数据 库 兼 容 的 
NUMERIC 或 
LONG INTEGER 


数据 库 兼 容 的 
NUMERIC 或 
FLOAT 


数据 库 兼 容 的 
NUMERIC 或 
DOUBLE 

数据 库 兼 容 的 
NUMERIC 或 
DECIMAL 


CHAR , 
VARCHAR 


CLOB , 
LONGVARCHAR 


NVARCHAR , 
NCHAR 


NCLOB 
RE ERE) FF 
流 类 型 


BLOB , 
LONGVARBINARY 


DateTypeHandler java.util.Date TIMESTAMP 


DateOnlyTypeHandler java.util.Date DATE 
TimeOnlyTypeHandler java.util.Date TIME 
SqlTimestampTypeHandler java.sql.Timestamp TIMESTAMP 
SqlDateTypeHandler java.sql.Date DATE 
SqlTimeTypeHandler java.sql.Time TIME 
ObjectTypeHandler Any ct 或 未 指 
VARCHAR- 任 何 
EnumTypeHandler Enumeration Type REREH ER 


型 ， 存 储 枚 举 的 和 
称 (而 不 是 索引 ) 


任何 兼容 的 
NUMERIC 或 
EnumOrdinalTypeHandler Enumeration Type DOUBLE 类 型 ， 
存储 枚 举 的 索引 
(而 不 是 名 称 ) < 


你 可 以 重 写 类 型 处 理 器 或 创建 你 自己 的 类 型 处 理 器 来 处 理 不 支持 的 或 非 标准 的 类 
型 。 具 体 做 法 为 : 实现 org.apache.ibatis.type.TypeHandler 接口 ， 或 继承 
一 个 很 便利 的 类 org.apache.ibatis.type.BaseTypeHandler ， 然 后 可 以 选择 
性 地 将 它 映射 到 一 个 JDBC 类 型 。 比 如 : 


// ExampleTypeHandler. java 
@MappedJdbcTypes(JdbcType. VARCHAR ) 
public class ExampleTypeHandler extends BaseTypeHandler<String> 


{ 


@Override 
public void setNonNullParameter(PreparedStatement ps, int i, S 
tring parameter, JdbcType jdbcType) throws SQLException { 
ps.setString(i, parameter); 


} 


@Override 
public String getNullableResult(ResultSet rs, String columnNam 
e) throws SQLException { 
return rs.getString(columnName) ; 


} 


@Override 
public String getNullableResult(ResultSet rs, int columnIndex) 
throws SQLException { 

return rs.getString(columnIndex); 


} 


@Override 
public String getNullableResult(CallableStatement cs, int colu 
mnIndex) throws SQLException { 
return cs.getString(columnIndex); 


} 
} 
<!-- mybatis-config.xml --> 
<typeHandlers> 


<typeHandler handler="org.mybatis.example.ExampleTypeHandler"/ 
> 


</typeHandlers> 


使 用 这 个 的 类 型 处 理 器 将 会 覆盖 已 经 存在 的 处 理 Java 的 String 类 型 属性 和 
VARCHAR 参数 及 结果 的 类 型 处 理 器 。 要 注意 MyBatis 不 会 需 探 数据 库 元 信息 来 
决定 使 用 哪 种 类 型 ， 所 以 你 必须 在 参数 和 结果 映射 中 指明 那 是 VARCHAR 类 型 的 字 
段 ， 以 使 其 能 够 绑 定 到 正确 的 类 型 处 理 器 上 。 这 是 因为 : MyBatis 直到 语句 被 执行 
才 清 楚 数据 类 型 。 


通过 类 型 处 理 器 的 泛 型 ，MyBatis 可 以 得 知 该 类 型 处 理 器 处 理 的 Java 类 型 ， 不 过 
这 种 行为 可 以 通过 两 种 方法 改变 : 


e。 在 类 型 处 理 器 的 配置 元 素 (typeHandler element) 上 增加 一 个 javaType & 
性 (比如 : javaType="String" ) ; 
o 在 类 型 处 理 器 的 类 上 (TypeHandler class) 增加 一 个 @Mappedtypes 注解 来 


指定 与 其 关联 的 Java 类 型 列表 。 如 果 在 javaType 属性 中 也 同时 指定 ， 则 
注解 方式 将 被 忽略 。 


可 以 通过 两 种 方式 来 指定 被 关联 的 JDBC 类 型 : 


e 在 类 型 处 理 器 的 配置 元 素 上 增加 一 个 javaType Be (re 
如 : javaType="VARCHAR ) ; 

e 在 类 类 型 处 理 器 的 类 上 (TypeHandler class) 增加 一 个 @MappedJdbcTypes 注 
解 来 指定 与 其 关联 的 JDBC 类 型 列表 。 如 果 在 javaType 属性 中 也 同时 指 
定 ， 则 注解 方式 将 被 忽略 。 


最 后 ， 可 以 让 MyBatis 为 你 查找 类 型 处 理 器 


<!-- mybatis-config.xml --> 
<typeHandlers> 

<package name="org.mybatis.example"/> 
</typeHandlers> 


注意 在 使 用 自动 检索 (autodiscovery) 功能 的 时 候 ， 只 能 通过 注解 方式 来 指定 
JDBC 的 类 型 。 


你 能 创建 一 个 泛 型 类 型 处 理 器 ， 它 可 以 处 理 多 于 一 个 类 。 为 达到 此 目的 ， 需 要 增加 
一 个 接收 该 类 作为 参数 的 构造 器 ， 这 样 在 构造 一 个 类 型 处 理 器 的 时 候 MyBatis 就 会 
传 入 一 个 具体 的 类 。 


//GenericTypeHandler.java 
public class GenericTypeHandler<E extends MyObject> extends Base 
TypeHandler<E> { 


private Class<E> type; 


public GenericTypeHandler(Class<E> type) { 
if (type == null) throw new IllegalArgumentException("Type a 
rgument cannot be null"); 
this.type = type; 
} 


EnumTypeHandler 和 EnumOrdinalTypeHandler 都 是 泛 型 类 型 处 理 器 
(generic TypeHandlers) ， 我 们 将 会 在 接 下 来 的 部 分 详细 探讨 。 


处 理 枚 举 类 型 


若 想 映射 枚 举 类 型 Enum ， 则 需要 从 EnumTypeHandler 或 者 
EnumOrdinalTypeHandler 中 选 一 个 来 使 用 。 


比如 说 我 们 想 存 储 取 近似 值 时 用 到 的 舍 入 模式 。 默 认 情 况 下 ，MyBatis 会 利用 
EnumTypeHandler 来 把 Enum 值 转换 成 对 应 的 名 字 。 


注意 EnumTypeHandler 在 茶 种 意义 上 来 说 是 比较 特别 的 ， 其 他 的 处 理 器 只 针对 
某 个 特定 的 类 ， 而 它 不 同 ， 它 会 处 理 任意 继承 了 Enum 的 类 。 


不 过 ， 我 们 可 能 不 想 存储 名 字 ， 相 反 我 们 的 DBA 会 坚持 使 用 整形 值 代码 。 那 也 一 
样 轻而易举 : 在 配置 文件 中 把 EnumordinalTypeHandler 加 到 typeHandlers 
中 即 可 ， 这样 每 个 RoundingMode 将 通过 他 们 的 序数 值 来 映射 成 对 应 的 整形 。 


<!-- mybatis-config.xml --> 
<typeHandlers> 
<typeHandler handler="org.apache.ibatis.type.EnumOrdinalTypeHa 
ndler" javaType="java.math.RoundingMode"/> 
</typeHandlers> 


但 是 怎样 能 将 同样 的 Enum 既 映 射 成 字符 串 又 映射 成 整形 呢 ? 


自动 映射 器 (auto-mapper) 会 自动 地 选用 EnumordinalTypeHandler 来 处 理 ， 
所 以 如 果 我 们 想 用 普通 的 _EnumTypeHandler ， 就 非 要 为 那些 SQL 语句 显 式 地 设 
置 要 用 到 的 类 型 处 理 器 不 可 。 


(下 一 节 才 开始 讲 映 射 器 文件 ， 所 以 如 果 是 首次 阅读 该 文档 ， 你 可 能 需要 先 越过 这 
一 步 ， 过 会 再 来 看 。) 


<!DOCTYPE mapper 
PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" 
"http://mybatis.org/dtd/mybatis-3-mapper.dtd"> 


<mapper namespace="org.apache.ibatis.submitted.rounding.Mapper'"> 
<resultMap type="org.apache.ibatis.submitted.rounding.User" 
id="usermap"> 
<id column="id" property="id"/> 
<result column="name" property="name"/> 
<result column="funkyNumber" property="funkyNumber"/> 
<result column="roundingMode" property="roundingMode"/> 
</resultMap> 


<select id="getUser" resultMap="usermap"> 
select * from users 
</select> 
<insert id="insert"> 
insert into users (id, name, funkyNumber, roundingMode) 
values ( 
#{id}, #{name}, #{funkyNumber}, #{roundingMode} 


</insert> 


<resultMap type="org.apache.ibatis.submitted.rounding.User" 
id="usermap2"> 
<id column="id" property="id"/> 
<result column="name" property="name"/> 
<result column="funkyNumber" property="funkyNumber"/> 
<result column="roundingMode" property="roundingMode" ty 
peHandler="org.apache. ibatis.type.EnumTypeHandler"/> 
</resultMap> 
<select id="getUser2" resultMap="usermap2"> 
select * from users2 
</select> 
<insert id="insert2"> 
insert into users2 (id, name, funkyNumber, roundingMode) 
values ( 
#{id}, #{name}, #{funkyNumber}, #{roundingMode, type 
Handler=org.apache.ibatis.type.EnumTypeHandler } 
) 


</insert> 


</mapper> 


注意 ， 这 里 的 select 语句 强制 使 用 resultMap 来 代替 resultType ° 


对 象 工 厂 (objectFactory ) 


MyBatis 每 次 创建 结果 对 象 的 新 实例 时 ， 它 都 会 使 用 一 个 对 象 工厂 

(ObjectFactory) 实例 来 完成 。 默 认 的 对 象 工 厂 需 要 做 的 仅仅 是 实例 化 目标 类 ， 
要 么 通过 默认 构造 方法 ， 要 么 ee ee o 
如 果 想 履 盖 对 象 工厂 的 默认 行为 ， 则 可 以 通过 创建 自己 的 对 象 工厂 来 实现 。 比 如 : 


// ExampleObjectFactory.java 
public class ExampleObjectFactory extends DefaultObjectFactory { 
public Object create(Class type) { 
return super.create(type); 


} 
public Object create(Class type, List<Class> constructorArgTyp 
es, List<Object> constructorArgs) { 
return super.create(type, constructorArgTypes, constructorAr 


gs); 


public void setProperties(Properties properties) { 
super.setProperties(properties) ; 


public <T> boolean isCollection(Class<T> type) { 
return Collection.class.isAssignableFrom(type); 


tt 


<!-- mybatis-config.xml --> 

<objectFactory type="org.mybatis.example.ExampleObjectFactory"> 
<property name="SomeProperty" value="100"/> 

</objectFactory> 


ObjectFactory 接口 很 简单 ， 它 包含 两 个 创建 用 的 方法 ， 一 个 是 处 理 默认 构造 方法 
的 ， 另 外 一 个 是 处 理 带 参数 的 构造 方法 的 。 最 后 ，setProperties 方法 可 以 被 用 来 
配置 ObjectFactory， 在 初始 化 你 的 ObjectFactory 实例 后 ，objectFactory 元 素 体 
中 定义 的 属性 会 被 传递 给 setProperties 方法 。 


464+ (plugins) 


MyBatis 允许 你 在 已 映射 语句 执行 过 程 中 的 茶 一 点 进行 拦截 调用 。 默 认 情 况 下 ， 
MyBatis 允许 使 用 插件 来 拦截 的 方法 调用 包括 : 


e Executor (update, query, flushStatements, commit, rollback, getTransaction, 
close, isClosed) 

e ParameterHandler (getParameterObject, setParameters) 

e ResultSetHandler (handleResultSets, handleOutputParameters) 

e StatementHandler (prepare, parameterize, batch, update, query) 


这 些 类 中 方法 的 细节 可 以 通过 查看 每 个 方法 的 签名 来 发 现 ， 或 者 直接 查看 MyBatis 


的 发 行 包 中 的 源 代码 。 BREE MM ERIM EES EWR ， 那么 你 应 该 很 好 的 
了 解 正在 重 写 的 方法 的 行为 。 因为 如 果 在 试图 修改 或 重 写 已 有 方法 的 行为 的 时 候 ， 


你 很 可 能 在 破坏 MyBatis 的 核心 模块 。 这 些 都 是 更 低层 的 类 和 方法 ， 所 以 使 用 插件 
的 时 候 要 特别 当心 。 


通过 MyBatis 提供 的 强大 机 制 ， 使 用 插件 是 非常 简单 的 ， 只 需 实现 Interceptor 接 
口 ， 并 指定 了 想 要 拦截 的 方法 签名 即 可 。 


// ExamplePlugin. java 
@Intercepts({@Signature( 
type= Executor.class, 
method = "update", 
args = {MappedStatement.class, Object.class})}) 
public class ExamplePlugin implements Interceptor { 
public Object intercept(Invocation invocation) throws Throwabl 
et 


return invocation.proceed(); 


} 
public Object plugin(Object target) { 
return Plugin.wrap(target, this); 


public void setProperties(Properties properties) { 


} 


} 
<!-- mybatis-config.xml --> 
<plugins> 
<plugin interceptor="org.mybatis.example.ExamplePlugin"> 
<property name="sSomeProperty" value="100"/> 
</plugin> 
</plugins> 


上 面 的 插件 将 会 拦截 在 Executor 实例 中 所 有 的 “Update” 方法 调用 ， 这 里 的 
Executor 是 负责 执行 低层 映射 语句 的 内 部 对 象 。 


NOTE 履 盖 配置 类 


除了 用 插件 来 修改 MyBatis 核心 行为 之 外 ， 还 可 以 通过 完全 履 盖 配置 类 来 达到 目 
的 。 只 需 继 承 后 履 盖 其 中 的 每 个 方法 ， 再 把 它 传递 到 
sqlSessionFactoryBuilder.build(myConfig) 方法 即 可 。 再 次 重申 ， 这 可 能 会 严重 影 
响 MyBatis 的 行为 ， 务 请 巾 之 又 惯 。 


配置 环境 (environments ) 


MyBatis 可 以 配置 成 适应 多 种 环境 ， 这 种 机 制 有 助 于 将 SQL 映射 应 用 于 多 种 数据 库 
之 中 ， 现 实情 况 下 有 多 种 理由 需要 这 么 做 。 例 如 ， 开 发 、 测 试 和 生产 环境 需要 有 不 
同 的 配置 ; 或 者 共享 相同 Schema 的 多 个 生产 数据 库 ， 想 使 用 相同 的 SQL 映射 。 
许多 类 似 的 用 例 。 


不 过 要 记 住 : 尽管 可 以 配置 多 个 环境 ， 每 个 SqlSessionFactory 实例 只 能 选择 其 


— o 


所 以 ， 如 果 你 想 连 接 两 个 数据 库 ， 就 需要 创建 两 个 SqlSessionFactory 实例 ， 每 个 
数据 库 对 应 一 个 。 而 如 果 是 三 个 数据 库 ， 就 需要 三 个 实例 ， 依 此 类 推 ， 记 起 来 很 简 
单 : 


© 每 个 数据 库 对 应 一 个 SqlSessionFactory 实例 


为 了 指定 创建 哪 种 环境 ， 只 要 将 它 作为 可 选 的 参数 传递 给 
SqlSessionFactoryBuilder 即 可 。 可 以 接受 环境 配置 的 两 个 方法 签名 是 : 


SqlSessionFactory factory = sqlSessionFactoryBuilder.build(reade 
r, environment); 

SqlSessionFactory factory = sqlSessionFactoryBuilder.build(reade 
r, environment, properties); 


如 果 忽 略 了 环境 参数 ， 那 么 默认 环境 将 会 被 加 载 ， 如 下 所 示 : 


SqlSessionFactory factory = sqlSessionFactoryBuilder.build(reade 
r); 

SqlSessionFactory factory = sqlSessionFactoryBuilder.build(reade 
r,properties); 


环境 元 素 定义 了 如 何 配置 环境 。 


<environments default="development"> 
<environment id="development"> 
<transactionManager type="JDBC"> 
<property name="..." value="..."/> 
</transactionManager> 
<dataSource type="POOLED"> 
<property name="driver" value="${driver}"/> 
<property name="url" value="${url}"/> 
<property name="username" value="${username}"/> 
<property name="password" value="${password}"/> 
</dataSource> 
</environment> 
</environments> 


注意 这 里 的 关键 点 : 


默认 的 环境 ID (比如 :default=”development”) ° 

每 个 environment 元 素 定义 的 环境 ID (比如 :id="development") ° 
事务 管理 器 的 配置 〈 比 如 :type="JDBC”) 。 

数据 源 的 配置 (比如 :type="POOLED”) 。 


默认 的 环境 和 环境 |D 是 一 目 了 然 的 。 随 你 怎么 命名 ， 只 要 保证 默认 环境 要 匹配 其 
中 一 个 环境 ID 。 


事务 管理 器 (transactionManager ) 
在 MyBatis 中 有 两 种 类 型 的 事务 管理 器 (也 就 是 type="[JDBC|IMANAGED]”) 


e JDBC - 这 个 配置 就 是 直接 使 用 了 JDBC 的 提交 和 回 滚 设置 ， 它 依赖 于 从 数据 
源 得 到 的 连接 来 管理 事务 范围 。 

e MANAGED - 这 个 配置 几乎 没 做 什么 。 它 从 来 不 提交 或 回 滚 一 个 连接 ， 而 是 让 
容器 来 管理 事务 的 整个 生命 周期 (比如 JEE 应 用 服务 器 的 上 下 文 ) © 默认 情 
况 下 它 会 关闭 连接 ， 然 而 一 些 容器 并 不 希望 这 样 ， 因 此 需要 将 
closeConnection 属性 设置 为 false 来 阻止 它 默 认 的 关闭 行为 。 例 如 : 


&lt;transactionManager type="MANAGED"&gt; 


&lt;property name="closeConnection" value="false"/&gt; 
&lt;/transactionManagerégt; 


NOTE 如 果 你 正在 使 用 Spring + MyBatis， 则 没有 必要 配置 事务 管理 器 ， 
Spring 模块 会 使 用 自 带 的 管理 器 来 覆盖 前 面 的 配置 。 


这 两 种 事务 管理 器 类 型 都 不 需要 任何 属性 。 它 们 不 过 是 类 型 别名 ， 换 和 句 话 说， 你 可 
以 使 用 TransactionFactory 接口 的 实现 类 的 完全 限定 名 或 类 型 别名 代替 它们 。 


JES 


为 


public interface TransactionFactory { 
void setProperties(Properties props); 
Transaction newTransaction(Connection conn); 


Transaction newTransaction(DataSource dataSource, TransactionI 
solationLevel level, boolean autoCommit); 


} 


任何 在 XML 中 配置 的 属性 在 实例 化 之 后 将 会 被 传递 给 setProperties() 方法 。 你 也 
需要 创建 一 个 Transaction 接口 的 实现 类 ， 这 个 接口 也 很 简单 : 


public interface Transaction { 
Connection getConnection() throws SQLException; 
void commit() throws SQLException; 
void rollback() throws SQLException; 
void close() throws SQLException; 


使 用 这 两 个 接口 ， 你 可 以 完全 自 定 义 MyBatis 对 事务 的 处 理 。 
数据 源 (dataSource ) 
dataSource 元 素 使 用 标准 的 JDBC 数据 源 接口 来 配置 JDBC 连接 对 象 的 资源 。 
e 许多 MyBatis 的 应 用 程序 将 会 按 示例 中 的 例子 来 配置 数据 源 。 然 而 它 并 不 是 必 


须 的 。 要 知道 为 了 方便 使 用 延迟 加 载 ， 数 据 源 才 是 必须 的 。 
有 三 种 内 建 的 数据 源 类 型 (也 就 是 type="TUNPOOLED|POOLED|JNDIY) 


UNPOOLED- 这 个 数据 源 的 实现 只 是 每 次 被 请 求 时 打开 和 关闭 连接 。 虽 然 一 点 
慢 ， 它 对 在 及 时 可 用 连接 方面 没有 性 能 要 求 的 简单 应 用 程序 是 一 个 很 好 的 选择 。 不 
同 的 数据 库 在 这 方面 表现 也 是 不 一 样 的 ， 所 以 对 某 些 数据 库 来 说 使 用 连接 池 并 不 重 
要 ， 这 个 配置 也 是 理想 的 。UNPOOLED 类 型 的 数据 源 仅仅 需要 配置 以 下 5 种 属 
PE: 


e driver 一 这 是 JDBC 驱动 的 Java 类 的 完全 限定 名 (并 不 是 JDBC 了 驱动 中 可 
能 包含 的 数据 源 类 ) 。 

e url 一 这 是 数据 库 的 JDBC URL 地 址 。 

e username 一 登录 数据 库 的 用 户 名 。 

e password 一 登录 数据 库 的 密码 。 

e defaultTransactionIsolationLevel 一 默认 的 连接 事务 隔离 级 别 。 

作为 可 选项 ， 你 也 可 以 传递 属性 给 数据 库 驱 动 。 要 这 样 做 ， 属 性 的 前 级 为 “driver.”， 

例如 : 


e driver.encoding=UTF8 


这 将 通过 DriverManagergetConnection(url,driverProperties) 方 法 传递 值 为 ”UTF8 
的 encoding 属性 给 数据 库 驱动 。 


POOLED- 这 种 数据 源 的 实现 利用 “ 池 " 的 概念 将 JDBC 连接 对 象 组 织 起 来 ， 有 避免 了 
创建 新 的 连接 实例 时 所 必需 的 初始 化 和 认证 时 间 。 这 是 一 种 使 得 并 发 Web 应 用 快 
速 响 应 请 求 的 流行 处 理 方式 。 


余 了 上 述 提 到 UNPOOLED 下 的 属性 外 ， 会 有 更 多 属性 用 来 配置 POOLED 的 数据 
a 


e poolMaximumActiveConnections 一 在 任意 时 间 可 以 存在 的 活动 (也 就 是 正 
在 使 用 ) 连接 数量 ， 默 认 值 : 10 

e poolMaximumIdleConnections 一 任意 时 间 可 能 存在 的 空闲 连接 数 。 

e poolMaximumCheckoutTime 一 在 被 强制 返回 之 前 ， 池 中 连接 被 检 出 

(checked out) 时 间 ， 上 默认 值 : 20000 BAY (Pp 204) 

e poolTimeTowait 一 这 是 一 个 底层 设置 ， 如 果 获 取 连 接 花费 的 相当 长 的 时 
间 ， 它 会 给 连接 池 打 印 状态 日 志 并 重新 尝试 获取 一 个 连接 (避免 在 误 配 置 的 情 
况 下 一 直 安 静 的 失败 ) > RUE : 20000 毫秒 ( 即 20 秒 ) © 

e poolPingQuery -发 送 到 数据 库 的 侦 测 查询 ， 用 来 检验 连接 是 否 处 在 正常 工 
作 秩 序 中 并 准备 接受 请 求 。 默 认 是 “NO PING QUERY SET”， 这 会 导致 多 数 数 
据 库 驱动 失败 时 带 有 一 个 恰当 的 错误 消息 。 

e poolPingEnabled 一 是 否 启 用 人 饥 测 查询 。 若 开启 ， 也 必须 使 用 一 个 可 执行 的 
SQL 语句 设置 poolPingQuery 属性 〈 最 好 是 一 个 非常 快 的 SQL) > RU 
fa. : false ° 

e poolPingConnectionsNotUsedFor 一 配置 poolPingQuery 的 使 用 频 度 
可 以 被 设置 成 匹配 具体 的 数据 库 连 接 超时 时 间 ， 来 避免 不 必要 的 侦 测 ， a 
值 :0 ( 即 所 有 连接 每 一 时 刻 都 被 侦 测 一 当然 仅 当 poolPingEnabled 为 true 
时 适用 ) o 


JNDI- 这 个 数据 源 的 实现 是 为 了 能 在 如 EJB 或 应 用 服务 器 这 类 容器 中 使 用 ， 容 器 
可 以 集中 或 在 外 部 配置 数据 源 ， 然 后 放置 一 个 JNDI 上 下 文 的 引用 。 这 种 数据 派 配 
置 只 需要 两 个 属性 : 


e initial_context 一 这 个 属性 用 来 在 InitialContext 中 了 寻找 上 下 文 〈 即 ， 
initialContext.lookup(initial_context)) 。 这 是 个 可 选 属性 ， 如 果 和 忽略， 那么 
data_source 属性 将 会 直接 从 InitialContext 中 寻找 。 

e data_source 一 这 是 引 te ere o 提供 
initial context 配置 时 会 在 其 返回 的 上 下 文中 进行 查找 ， 没 有 提供 a 直接 在 
InitialContext 中 查找 。 


和 其 他 数据 源 配 置 类 似 ， 可 以 通过 添加 前 级 “env.” 直 接 把 属性 传递 给 初始 上 下 文 。 
比如 : 


e env.encoding=UTF8 


这 就 会 在 初始 上 下 文 (InitialContext) 实例 化 时 往 它 的 构造 方法 传递 值 为 UTF8 
的 encoding 属性 。 


通过 需要 实现 接口 org.apache.ibatis.datasource.DataSourceFactory ， 
也 可 使 用 任何 第 三 方 数据 源 ，: 


public interface DataSourceFactory { 
void setProperties(Properties props); 
DataSource getDataSource(); 


} 


org.apache.ibatis.datasource.unpooled. UnpooledDataSourceFactory 可 
被 用 作 父 类 来 构建 新 的 数据 源 适 配器 ， 比 如 下 面 这 段 插入 C3P0 数据 源 所 必需 的 代 
码 : 


import org.apache.ibatis.datasource.unpooled.UnpooledDataSourceF 
actory, 
import com.mchange.v2.c3p0.ComboPooledDataSource; 


public class C3PODataSourceFactory extends UnpooledDataSourceFac 
tory { 


public C3PODataSourceFactory() { 
this.dataSource = new ComboPooledDataSource(); 


} 
} 


为 了 令 其 工作 ， 为 每 个 需要 MyBatis 调用 的 setter 方法 中 增加 一 个 属性 。 下 面 是 一 
个 可 以 连接 至 PostgreSQL 数据 库 的 例子 


<dataSource type="org.myproject.C3PODataSourceFactory"> 
<property name="driver" value="org.postgresql.Driver"/> 
<property name="url" value="jdbc:postgresql:mydb"/> 
<property name="username" value="postgres"/> 
<property name="password" value="root"/> 

</dataSource> 


databaseldProvider 


MyBatis 可 以 根据 不 同 的 数据 库 厂 商 执行 不 同 的 语 匈 ， 这 种 多 厂商 的 支持 是 基于 了 映 
射 语 名 中 的 databaseId 属性 。 MyBatis 会 加 载 不 带 databaseId 属性 和 带 有 
匹配 当前 数据 库 databaseId 属性 的 所 有 语句 。 如 果 同 时 找到 带 有 
databaseId 和 不 带 databaseId 的 相同 语 姻 ， 则 后 者 会 被 舍弃 。 为 支持 多 厂 
商 特 性 只 要 像 下 面 这 样 在 mybatis-config.xml 文件 中 加 入 databaseIdProvider 
即 可 : 


<databaseIdProvider type="DB_VENDOR" /> 


这 里 的 DB_ VENDOR 会 通过 DatabaseMetaData#getDatabaseProductName() 
返回 的 字符 串 进行 设置 。 由 于 通常 情况 下 这 个 字符 串 都 非常 长 而 且 相 同 产品 的 不 同 
版 本 会 返回 不 同 的 值 ， 所 以 最 好 通过 设置 属性 别名 来 使 其 变 短 ， 如 下 : 


<databaseIdProvider type="DB_VENDOR"> 
<property name="SQL Server" value="sqlserver"/> 
<property name="DB2" value="db2"/> 
<property name="Oracle" value="oracle" /> 
</databaselIdProvider> 


在 有 properties "t > DB_VENDOR databaseldProvider 的 将 被 设置 为 第 一 个 能 匹 
配 数据 库 产品 名 称 的 属性 键 对 应 的 值 ， 如 果 没 有 匹配 的 属性 将 会 设置 为 “null'。 在 
这 个 例子 中 ， 如 果 getDatabaseProductName() 返回 “Oracle (DataDirect)”， 
databaseld 将 被 设置 为 “oracle”。 


你 可 以 通过 实现 接口 org.apache.ibatis.mapping.DatabaseIdProvider 并 在 
mybatis-config.xml 中 注册 来 构建 自己 的 DatabaseldProvider : 


public interface DatabaseIdProvider { 

void setProperties(Properties p); 

String getDatabaseId(DataSource dataSource) throws SQLExceptio 
n; 


} 


映射 器 (mappers ) 


既然 MyBatis 的 行为 已 经 由 上 述 元 素 配置 完了 ， 我 们 现在 就 要 定义 SQL 映射 语句 

了 。 但 是 首先 我 们 需要 告诉 MyBatis 到 哪里 去 找到 这 些 语 的 。 Java 在 自动 查找 这 

D ， 所 以 最 佳 的 方式 是 告诉 MyBatis 到 哪里 去 找 映射 文 

件 。 你 可 以 使 用 相对 于 类 路 径 的 资源 引用 ， 或 完全 限定 资源 定位 符 (包括 
File:/// 的 URL) ， 或 类 名 和 包 名 等 。 例 如 : 


<!-- Using classpath relative resources --> 

<mappers> 
<mapper resource="org/mybatis/builder/AuthorMapper.xml"/> 
<mapper resource="org/mybatis/builder/BlogMapper . xm1"/> 
<mapper resource="org/mybatis/builder/PostMapper .xml"/> 

</mappers> 


<!-- Using url fully qualified paths --> 

<mappers> 
<mapper url="file:///var/mappers/AuthorMapper .xm1"/> 
<mapper url="file:///var/mappers/BlogMapper . xm1"/> 
<mapper url="file:///var/mappers/PostMapper . xm1"/> 

</mappers> 


<!-- Using mapper interface classes --> 

<mappers> 
<mapper class="org.mybatis.builder.AuthorMapper'"/> 
<mapper class="org.mybatis.builder .BlogMapper"/> 
<mapper class="org.mybatis.builder.PostMapper"/> 

</mappers> 


<!-- Register all interfaces in a package as mappers --> 
<mappers> 

<package name="org.mybatis.builder"/> 
</mappers> 


这 些 配 置 会 告诉 了 MyBatis 去 哪里 找 映 射 文件 ， 剩 下 的 细节 就 应 该 是 每 个 SQL 映 
射 文件 了 ， ee ee 


Mapper XML 文件 


MyBatis #9 SJE IRA TE ABATE) + LAE oT EM AH RX ， 
映射 器 的 XML 文件 就 显得 相对 简单 。 如 果 拿 它 跟 具 有 相同 功能 的 JDBC 代码 进行 
对 比 ， 你 会 立即 发 现 省 掉 了 将 近 95% 的 代码 。MyBatis 就 是 针对 SQL 构建 的 ， 并 
且 比 普通 的 方法 做 的 更 好 。 


SQL 映射 文件 有 很 少 的 几 个 顶级 元 素 (按照 它们 应 该 被 定义 的 顺序 ) 


e cache 一 给 定 命名 空间 的 缓存 配置 

e cache-ref 一 其 他 命名 空 HAAREN o 

e resultMap 一 是 最 复杂 也 是 最 强大 的 元 素 ， 用 来 描述 如 何 从 数据 库 结果 集中 
来 加 载 对 象 。 


e NE 
5 zÀ 








ea — 可 被 其 他 语 h 引用 的 可 重用 语 a] IR © 
insert 一 映射 插入 语句 
update 一 映射 更 新 语句 
delete 一 映射 删除 语句 
select — IRA 471978 4 


下 一 部 分 将 从 语句 本 身 开始 来 描述 每 个 元 素 的 细节 。 


select 


查询 语句 是 MyBatis 中 最 常用 的 元 素 之 一 ， 光 能 把 数据 存 到 数据 库 中 价值 并 不 大 ， 
ho RAK fj i ， 多 数 应 用 也 都 是 查 询 比 修改 要 频繁 。 对 每 个 插入 、 更 
新 或 删除 操作 ， 通 常 对 应 多 个 查询 操作 。 这 是 MyBatis 的 基本 原则 之 一 ， 也 是 将 焦 
点 和 努力 放 到 查询 和 结果 映射 的 原因 。 简 单 查询 的 select 元 素 是 非常 简单 的 。 比 
如 : 


<select id="SelectPerson" parameterType="int" resultType="hashma 
p"> 

SELECT * FROM PERSON WHERE ID = #{id} 
</select> 


这 个 语句 被 称 作 selectPerson， 接 受 一 个 int (或 Integer) 类 型 的 参数 ， 并 返回 一 
个 HashMap 类 型 的 对 象 ， 其 中 的 键 是 列 名 ， 值 便 是 结果 行 中 的 对 应 值 。 


注意 参数 符号 : 


#{id} 


这 就 告诉 MyBatis 创建 一 个 预 处 理 语 句 参数 ， 通 过 JDBC， 这 样 的 一 个 参数 在 SQL 
中 会 由 一 个 “?" 来 标识 ， 并 被 传递 到 一 个 新 的 预 处 理 语 名 中 ， 就 像 这 样 : 


// Similar JDBC code, NOT MyBatis... 

String selectPerson = "SELECT * FROM PERSON WHERE ID=?"; 
PreparedStatement ps = conn.prepareStatement(selectPerson) ; 
ps.setiInt(1, id); 


当然 ， 这 需要 很 多 单独 的 JDBC 的 代码 来 提取 结果 并 将 它们 映射 到 对 和 象 实例 中 
就 是 MyBatis 节省 你 时 间 的 地 方 。 我 们 需要 深入 了 解 参数 和 结果 映射 ， 细 节 部 
们 下 面 来 了 解 。 


select 元 素 有 很 多 属性 允许 你 配置 ， 来 决定 每 条 语句 的 作用 细节 。 


分 我 


<select 
id="selectPerson" 
parameterType="int" 
parameterMap="deprecated" 
resultType="hashmap" 
resultMap="personResultMap" 
flushCache="false" 
useCache="true" 
timeout="10000" 
fetchSize="256" 
statementType="PREPARED" 
resultSetType="FORWARD_ONLY"> 


Select Attributes 
属性 描述 
id 在 命名 空间 中 唯一 的 标识 符 ， 可 以 被 用 来 引用 这 条 语句 。 


将 会 传 入 这 条 语句 的 参数 类 的 完全 限定 名 或 别名 。 这 个 属 
parameterType ”性 是 可 选 的 ， 因 为 MyBatis 可 以 通过 TypeHandler 推断 出 
具体 传 入 语句 的 参数 ， 上 默认 值 为 unset。 


parameterMap 





从 这 条 语句 中 返回 的 期 望 类 型 的 类 的 完全 限定 名 或 别名 。 
注意 如 果 是 集合 情形 ， 那 应 该 是 集合 可 以 包含 的 类 型 ， 而 
不 能 是 集合 本 身 。 使 用 resultType 或 resultMap， 但 不 能 
同时 使 用 。 


resultType 


外 部 resultMap 的 命名 引用 。 结 果 集 的 映射 是 MyBatis 最 
强大 的 特性 ， 对 其 有 一 个 很 好 的 理解 的 话 ， 许 多 复杂 映射 
的 情形 都 能 迎刃而解 。 使 用 resultMap 或 resultType， 但 
不 能 同时 使 用 。 


resultMap 


flushCache 


useCache 


timeout 


fetchSize 


statementType 


resultSetType 


databaseld 


resultOrdered 


resultSets 


将 其 设置 为 true， 任 何 时 候 只 要 语 匈 被 调用 ， 都 会 导致 本 
地 缓存 和 二 级 缓存 都 会 被 清空 ， 默 认 值 false ° 


将 其 设置 为 true， 将 会 导致 本 条 语句 的 结果 被 二 级 缓存 ， 
默认 值 : 对 select AŽ A true ° 


这 个 设置 是 在 抛 出 异常 之 前 ， 驱 动 程序 等 待 数据 库 返 回 请 
求 结果 的 秒 数 。 默 认 值 为 unset (依赖 驱动 ) 。 


这 是 尝试 影响 驱动 程序 每 次 批量 返回 的 结果 行 数 和 这 个 设 
置 值 相等 。 上 默认 值 为 unset (依赖 驱动 ) © 


STATEMENT > PREPARED 或 CALLABLE 的 一 个 。 这 会 
让 MyBatis 分 别 使 用 Statement，PreparedStatement 或 
CallableStatement， 默 认 值 : PREPARED 。 


FORWARD_ONLY > SCROLL_SENSITIVE 或 
SCROLL_INSENSITIVE Ft — A > RIEA unset ( 依 
赖 驱动 ) © 


如 果 配 置 了 databaseldProvider > MyBatis 会 加载 所 有 的 
不 带 databaseld 或 匹配 当前 databaseld 47% 4) ; 如 果 带 
或 者 不 带 的 语句 都 有 ， 则 不 带 的 会 被 忽略 。 


这 个 设置 仅 针对 诅 套 结果 select 语句 适用 : 如 果 为 true， 
就 是 假设 包含 了 诅 套 结果 集 或 是 分 组 了 ， 这 样 的 话 当 返 回 
一 个 主 结 果 行 的 时 候 ， 就 不 会 发 生 有 对 前 面 结果 集 的 引用 
的 情况 。 这 就 使 得 在 获取 上 获 套 的 结果 集 的 时 候 不 至 于 导致 
内 存 不 够 用 。 默 认 值 : false 。 


返回 的 结果 集 并 每 个 结果 集 给 一 个 名 称 ， 名 称 是 去 号 分 陋 
的 。 


insert, update 和 delete 


数据 变更 语句 insert > update 和 delete 的 实现 非常 接近 : 


<insert 
id="insertAuthor" 
parameterType="domain.blog.Author" 
flushCache="true" 
statementType="PREPARED" 
keyProperty="" 
keyColumn="" 
useGeneratedKeys="" 
timeout="20"> 


<update 
id="updateAuthor" 
parameterType="domain.blog.Author" 
flushCache="true" 
statementType="PREPARED" 
timeout="20"> 


<delete 
id="deleteAuthor" 
parameterType="domain.blog.Author" 
flushCache="true" 
statementType="PREPARED" 
timeout="20"> 


Insert, Update 和 Delete 的 属性 


属性 
id 


parameterType 


~~parameterMap~~ 


flushCache 


timeout 


statementType 


useGeneratedKeys 


keyProperty 


keyColumn 


databaseld 


描述 
命名 空间 中 的 唯一 标识 符 ， 可 被 用 来 代表 这 条 语句 。 
将 要 传 入 语句 的 参数 的 完全 限定 类 名 或 别名 。 这 个 属 


性 是 可 选 的 ， 因 为 MyBatis 可 以 通过 TypeHandler 推 
断 出 具体 传 入 语句 的 和 参数， 默认 值 为 unset 。 


a 立 Anke iE Š 





将 其 设置 为 true， 任 和 何 时 候 只 要 语句 被 调用 ， 都 会 导 
致 本 地 缓存 和 二 级 缓存 都 会 被 清空 ， 默 认 值 : true (对 
应 插入 、 更 新 和 删除 语句 ) 。 


这 个 设置 是 在 抛 出 异常 之 前 ， 驱 动 程序 等 待 数据 库 返 
回 请 求 结果 的 秒 数 。 默 认 值 为 unset (依赖 驱动 ) © 


STATEMENT ，PREPARED 或 CALLABLE 的 一 个 。 
这 会 让 MyBatis 分 别 使 用 Statement， 
PreparedStatement 或 CallableStatement， 默 认 值 : 
PREPARED 。 


( 仅 对 insert 和 update 有 用 ) 这 会 令 MyBatis 使 用 
JDBC 的 getGeneratedKeys 方法 来 取出 由 数据 库 内 
部 生成 的 主键 (比如 : 像 MySQL 和 SQL Server 这 样 
的 关系 数据 库 管 理 系 统 的 自动 递增 字段 ) ， 默 认 值 : 
false。 


( 仅 对 insert 和 update 有 用 ) 唯一 标记 一 个 属性 ， 
MyBatis 会 通过 getGeneratedKeys 的 返回 值 或 者 通过 
insert 语句 的 selectKey 子 元 素 设 置 它 的 键 值 ， 默 
ih: unset 。 如 果 和 希望 得 到 多 个 生成 的 列 ， 也 可 以 
是 运 号 分 隔 的 属性 名 称 列 表 。 


( 仅 对 insert 和 update 有 用 ) 通过 生成 的 键 值 设 置 表 
中 的 列 名 ， 这 个 设置 仅 在 某 些 数据 库 ( 像 
PostgreSQL) 是 必须 的 ， 当 主键 列 不 是 表 中 的 第 一 列 
的 时 候 需 要 设置 。 如 果 希 望 得 到 多 个 生成 的 列 ， 也 可 
以 是 过 号 分 隔 的 属性 名 称 列表 。 


如 果 配 置 了 databaseldProvider > MyBatis 会 加 载 所 
有 的 不 带 databaseld 或 匹配 当前 databaseld 的 语 
4) ; 如 果 带 或 者 不 带 的 语句 都 有 ， 则 不 带 的 会 被 忽 
wk o 


下 面 就 是 insert，uUpdate 和 delete 语句 的 示例 : 


<insert id="insertAuthor"> 
insert into Author (id, username, password, email, bio) 
values (#{id},#{username}, #{password}, #{email},#{bio}) 
</insert> 


<update id="updateAuthor"> 
update Author set 
username = #{username}, 
password = #{password}, 
email = #{email}, 


bio = #{bio} 
where id = #{id} 
</update> 


<delete id="deleteAuthor"> 
delete from Author where id = #{id} 
</delete> 


如 前 所 述 ， 插 入 语句 的 配置 规则 更 加 丰富 ， 在 插入 语句 里 面 有 一 些 额 外 的 属性 和 子 
元 素 用 来 处 理 主键 的 生成 ， 而 有 全 有 多 种 生成 方式 。 


首先 ， 如 果 你 的 数据 库 支持 自动 生成 主键 的 字段 (比如 MySQL 和 SQL Server) ， 
那么 你 可 以 设置 UseGeneratedKeys=”true”， 然 后 再 把 keyProperty 设置 到 目标 属 
性 上 就 OK 了 。 例 如 ， 如 果 上 面 的 Author 表 已 经 对 id 使 用 了 自动 生成 的 列 类 型 ， 那 
么 语句 可 以 修改 为 : 


<insert id="insertAuthor" useGeneratedKeys="true" 
keyProperty="id"> 
insert into Author (username, password, email, bio) 
values (#{username}, #{password},#{email}, #{bio}) 
</insert> 


对 于 不 支持 自动 生成 类 型 的 数据 库 或 可 能 不 支持 自动 生成 主键 JDBC 驱动 来 说 ， 
MyBatis 有 另外 一 种 方法 来 生成 主键 。 


这 里 有 一 个 简单 (HERA) 的 示例 ， 它 可 以 生成 一 个 随机 ID 〈 你 最 好 不 要 这 么 
做 ， 但 这 里 展示 了 MyBatis 处 理 问 题 的 灵活 性 及 其 所 关心 的 广度 ) : 


<insert id="insertAuthor"> 
<selectKey keyProperty="id" resultType="int" order="BEFORE"> 
select CAST(RANDOM()*1000000 as INTEGER) a from SYSIBM.SYSDU 
MMY1 
</selectkey> 
insert into Author 
(id, username, password, email,bio, favourite section) 
values 
(#{id}, #{username}, #{password}, #{email}, #{bio}, #{favour 
iteSection, jdbcType=VARCHAR} ) 
</insert> 


在 上 面 的 示例 中 ，selectKey 元 素 将 会 首先 运行 ，Author 的 id 会 被 设置 ， 然 后 插入 
语 钨 会 被 调用 。 这 给 你 了 一 个 和 数据 库 中 来 处 理 自 动 生 成 的 主键 类 似 的 行为 ， 避 免 
了 使 Java 代码 变 得 复杂 。 


selectKey 元 素描 述 如 下 : 


<selectKey 
keyProperty="id" 
resultType="int" 
order="BEFORE" 
statementType="PREPARED"> 


selectKey 的 属性 


属性 描述 
sa 全 外 > 4x ak at 2 = , A A y 得 
ain TIA selectKey 74 4) 26 RM ARIE BAY BRB o ho RA eZ 4 


到 多 个 生成 的 列 ， 也 可 以 是 过 号 分 隔 的 属性 名 称 列表 。 
多 


匹配 属性 的 返回 结果 集中 的 列 名 称 。 如 果 和 希望 得 到 
成 的 列 ， 也 可 以 是 过 号 分 隔 的 属性 名 称 列表 。 


结果 的 类 型 。MyBatis 通常 可 以 推算 出 来 ， 但 是 为 了 更 加 
确定 写 上 也 不 会 有 什么 问题 。MyBatis 允许 任何 简单 类 型 

resultType 用 作 主 键 的 类 型 ， 包 括 字 符 串 。 如 果 布 望 作用 于 多 个 生成 
的 列 ， 则 可 以 使 用 一 个 包含 期 望 属性 的 Object 或 一 个 
Map ° 


这 可 以 被 设置 为 BEFORE 或 AFTER 。 如 果 设 置 为 
BEFORE， 那 么 它 会 首先 选择 主键 ， 设 置 keyProperty 然 

order 后 执行 插入 语句 。 如 果 设 置 为 AFTER， 那 么 先 执行 插入 
语句 ， 然 后 是 selectKey 元 素 - 这 和 像 Oracle 的 数据 库 相 
似 ， 在 插入 语句 内 部 可 能 有 上 获 入 索引 调用 。 


与 前 面相 同 ，MyBatis 支持 STATEMENT > PREPARED 
statementType ”和 CALLABLE 语句 的 映射 类 型 ， 分 别 代 表 
PreparedStatement 和 CallableStatement 类 型 。 


keyColumn 


sql 


这 个 元 素 可 以 被 用 来 定义 可 重用 的 SQL 代码 段 ， 可 以 包含 在 其 他 语句 中 。 它 可 以 
被 静态 地 (在 加 载 参 数 ) 参数 化 . 不 同 的 属性 值 通过 包含 的 实例 变化 , 比如 : 


<sql id="userColumns"> ${alias}.id,${alias}.username, ${alias}.pa 
ssword </sql> 


这 个 SQL 片段 可 以 被 包含 在 其 他 语句 中 ， 例 如 : 


<select id="SelectUsers" resultType="map"> 
select 
<include refid="userColumns"><property name="alias" value="t 
1"/></include>, 
<include refid="userColumns"><property name="alias" value="t 
2"/></include> 
from some_table t1 
cross join some_table t2 
</select> 


属性 值 可 以 用 于 包含 的 refid 属 性 或 者 包含 的 字句 里 面 的 属性 值 ， 例如: 


<sql id="sometable"> 


${prefix}Table 
</sql> 
<sql id="someinclude"> 
from 
<include refid="${include_target}"/> 
</sql> 


<select id="Select" resultType="map"> 
select 
field1, field2, field3 
<include refid="someinclude"> 
<property name="prefix" value="Some"/> 
<property name="include_target" value="sSometable"/> 
</include> 
</select> 


参数 (Parameters ) 


前 面 的 所 有 语句 中 你 所 见 到 的 都 是 简单 参数 的 例子 ， 实 际 上 参数 是 MyBatis 非常 强 
大 的 元 素 ， 对 于 简单 的 做 法 ， 大 概 90% 的 情况 参数 都 很 少 ， 比 如 : 


<select id="SelectUsers" resultType="User"> 
select id, username, password 
from users 
where id = #{id} 

</select> 


上 面 的 这 个 示例 说 明了 一 个 非常 简单 的 命名 参数 映射 。 参 数 类 型 被 设置 为 int ， 
这 样 这 个 参数 就 可 以 被 设置 成 任何 内 容 。 原 生 的 类 型 或 简单 数据 类 型 (比如 整 型 和 
字符 串 ) 因为 没有 相关 属性 ， 它 会 完全 用 参数 值 来 替代 。 然 而 ， 如 果 传 入 一 个 复杂 
的 对 象 ， 行 为 就 会 有 一 点 不 同 了 。 上 比如 : 


<insert id="insertUser" parameterType="User"> 
insert into users (id, username, password) 
values (#{id}, #{username}, #{password}) 
</insert> 


如 果 User 类 型 的 参数 对 象 传递 到 了 语句 中 ，id、username 和 password 属性 将 会 
被 查找 ， 然 后 将 它们 的 值 传 入 预 处 理 语句 的 参数 中 。 


这 点 对 于 向 语句 中 传 参 是 比较 好 的 而 且 又 简单 ， 不 过 和 参数 映射 的 功能 远 不 止 于 此 。 
首先 ， 像 MyBatis 的 其 他 部 分 一 样 ， 参 数 也 可 以 指定 一 个 特殊 的 数据 类 型 。 


#{property, javaType=int, jdbcType=NUMERIC} 


4% MyBatis 的 剩余 部 分 一 样 ，javaType 通常 可 以 从 参数 对 象 中 来 去 确定 ， 前 提 是 只 
要 对 象 不 是 一 个 HashMap。 那 么 javaType 应 该 被 确定 来 保证 使 用 正确 类 型 处 理 


ga 
o 
ao 


NOTE 如 果 null 被 当 作 值 来 传递 ， 对 于 所 有 可 能 为 空 的 列 ，JDBC Type 是 需要 
的 。 你 可 以 自己 通过 阅读 预 处 理 语句 的 setNull() 方法 的 JavaDocs 文档 来 研究 这 种 
情况 。 

为 了 以 后 定制 类 型 处 理 方式 ， 你 也 可 以 指定 一 个 特殊 的 类 型 处 理 器 类 (或 别名 ) > 
比如 : 


#{age, JavaType=int, jdbcType=NUMERIC, typeHandler=MyTypeHandler } 


尽管 看 起 来 配置 变 得 越 来 越 繁 琐 ， 但 实际 上 是 很 少 去 设置 它们 。 
对 于 数值 类 型 ， 还 有 一 个 小 数 保 留 位 数 的 设置 ， 来 确定 小 数 点 后 保留 的 位 数 。 


#{height, javaType=double, jdbcType=NUMERIC, numericScale=2} 


最 后 ，mode 属性 允许 你 指定 IN，OUT 或 INOUT 参数 。 如 果 参 数 为 OUT 或 
INOUT， 参 数 对 象 属 性 的 站 实 值 将 会 被 改变 ， 就 像 你 在 获取 输出 参数 时 所 期 望 的 那 
样 。 如 果 mode 为 OUT (或 INOUT) ， 而 且 jdbcType 为 CURSOR( 也 就 是 
Oracle 的 REFCURSOR)， 你 必须 指定 一 个 resultMap 来 映射 结果 集 到 参数 类 型 。 
要 注意 这 里 的 javaType 属性 是 可 选 的 ， 如 果 左 边 的 空白 是 jdbcType 的 CURSOR 
类 型 ， 它 会 自动 地 被 设置 为 结果 集 。 


#{department, mode=OUT, jdbcType=CURSOR, javaType=ResultSet, res 
ultMap=departmentResultMap} 


MyBatis 也 支持 很 多 高 级 的 数据 类 型 ， 比 如 结构 体 ， 但 是 当 注 册 out 参数 时 你 必须 
告诉 它 语句 类 型 名 称 。 比 如 (再 次 提示 ， 在 实际 中 要 像 这 样 不 能 换行 ) 


#{middleInitial, mode=OUT, jdbcType=STRUCT, jdbcTypeName=MY_TYPE 
, resultMap=departmentResultMap} 


尽管 所 有 这 些 强大 的 选项 很 多 时 候 你 只 简单 指定 属性 名 ， 其 他 的 事情 MyBatis 会 自 
己 去 推断 ， 最 多 你 需要 为 可 能 为 空 的 列 名 指定 jdbcType ° 


#{firstName} 
#{middleInitial, jdbcType=VARCHAR} 
#{lastName} 


字符 串 替 换 


默认 情况 下 ,使 用 #(} 格 式 的 语法 会 导致 MyBatis 创建 预 处 理 语句 属性 并 安全 地 设置 
值 (比如 ?) 。 这 样 做 更 安全 ， 更 迅速 ， 通 常 也 是 首选 做 法 ， 不 过 有 时 你 只 是 想 直 
接 在 SQL 语句 中 插入 一 个 不 改变 的 字符 囊 。 比 如 ， 像 ORDER BY， 你 可 以 这 样 来 
使 用 : 


ORDER BY ${columnName} 


这 里 MyBatis 不 会 修改 或 转 义 字符 串 。 

NOTE 以 这 种 方式 接受 从 用 户 输 出 的 内 容 并 提供 给 语句 中 不 变 的 字符 串 是 不 安全 
的 ， 会 导致 潜在 的 SQL 注入 攻击 ， 因 此 要 么 不 允许 用 户 输 入 这 些 字 段 ， 要 么 自行 
转 义 并 检验 。 


Result Maps 
resultMap 元 素 是 MyBatis 中 最 重要 最 强大 的 元 素 。 它 就 是 让 你 远离 90% 的 需要 从 


结果 集中 取出 数据 的 JDBC 代码 的 那个 东西 , 而 且 在 一 些 情形 下 允许 你 做 一 些 
JDBC 不 支持 的 事 情 。 SKE 编写 相似 于 对 复杂 语句 联合 映射 这 些 等 同 的 代码 ， 


也 许可 以 跨 过 上 千 行 的 代码 。ResultMap 的 设计 就 是 简单 语句 不 需要 明确 的 结果 映 
射 ,而 很 多 复杂 语句 确实 需要 描述 它们 的 关系 。 


你 已 经 看 到 简单 映射 语句 的 示例 了 ,但 没有 明确 的 resultMap。 比如: 


<select id="selectUsers" resultType="map"> 
select id, username, hashedPassword 
from some_table 
where id = #{id} 

</select> 


这 样 一 个 语句 简单 作用 于 所 有 列 被 自动 映射 到 HashMap 的 键 上 ,这 由 resultType & 
性 指定 。 这 在 很 多 情况 下 是 有 用 的 ,但 是 HashMap 不 能 很 好 描述 一 个 领域 模型 。 那 
样 你 的 应 用 程序 将 会 使 用 JavaBeans 或 POJOs(Plain Old Java Objects, 普 通 Java 
对 象 ) 来 作为 领域 模型 。MyBatis 对 两 者 都 支持 。 看 看 下 面 这 个 JavaBean: 


package com.someapp.model; 
public class User { 
private int id; 
private String username; 
private String hashedPassword; 


public int getId() { 
return id; 


} 
public void setId(int id) { 
this.id = id; 


} 
public String getUsername() { 
return username; 


public void setUsername(String username) { 
this.username = username; 


public String getHashedPassword() { 
return hashedPassword; 


public void setHashedPassword(String hashedPassword) { 
this.hashedPassword = hashedPassword; 


} 
} 


基于 JavaBean 的 规范 ;上面 这 个 类 有 3 个 属性 :id,username 和 hashedPassword 。 
这 些 在 select 语句 中 会 精确 匹配 到 列 名 。 


这 样 的 一 个 JavaBean 可 以 被 映射 到 结果 集 ,就 像 映 射 到 HashMap 一 样 简单 。 


<select id="selectUsers" resultType="com.someapp.model.User"> 
select id, username, hashedPassword 
from some_table 
where id = #{id} 

</select> 


要 记 住 类 型 别名 是 你 的 伙伴 。 使 用 它们 你 可 以 不 用 输入 类 的 全 路 径 。 比 如: 


<!-- In mybatis-config.xml file --> 
<typeAlias type="com.someapp.model.User" alias="User"/> 


<!-- In SQL Mapping XML file --> 

<select id="SelectUsers" resultType="User"> 
select id, username, hashedPassword 
from some_table 
where id = #{id} 

</select> 


这 些 情况 下 ,MyBatis 会 在 幕后 自动 创建 一 个 ResultMap, 基 于 属性 名 来 映射 列 到 
JavaBean 的 属性 上 。 如 果 列 名 没有 精确 匹配 ,你 可 以 在 列 名 上 使 用 select 字句 的 别 
名 (一 个 基本 的 SQL 特性 ) 来 匹配 标签 。 比 如 : 


<select id="SelectUsers" resultType="User"> 


select 
user_id as Td 
user_name as "userName", 
hashed_password as "hashedPassword" 


from some_table 
where id = #{id} 
</select> 


ResultMap RRA UA OAT ART RS TERERAA AEA A o HE 
简 单 的 示例 不 需要 比 你 看 到 的 更 多 东西 。 只 是 出 于 示例 的 原因 , 让 我 们 来 看 看 最 后 
一 个 示例 中 外 部 的 resultMap 是 什么 样子 的 ,这 也 是 解决 列 名 不 匹配 的 另外 一 种 方 
Ñ o 


<resultMap id="userResultMap" type="User"> 
<id property="id" column="user_id" /> 
<result property="username" column="user_name"/> 


<result property="password" column="hashed_password"/> 
</resultMap> 


引用 它 的 语句 使 用 resultMap 属性 就 行 了 (注意 我 们 去 掉 了 resultType 属性 )。 比 如 : 


<select id="SelectUsers" resultMap="userResultMap"> 
select user_id, user_name, hashed_password 
from some_table 
where id = #{id} 

</select> 


如 果 世 界 总 是 这 么 简单 就 好 了 。 


高 级 结果 映射 


MyBatis 创建 的 一 个 想法 : 数据 库 不 用 永远 是 你 想 要 的 或 需要 它们 是 什么 样 的 。 而 我 
们 最 喜欢 的 数据 库 最 好 是 第 三 范式 或 BCNF 模式 ,但 它们 有 时 不 是 。 如 果 可 能 有 一 
个 单独 的 数据 库 映射 ,所 有 应 用 程序 都 可 以 使 用 它 ,这 是 非常 好 的 ,但 有 时 也 不 是 。 结 
果 了 映射 就 是 MyBatis 提供 处 理 这 个 问题 的 答案 。 


比如 ,我 们 如 何 映射 下 面 这 个 语句 ? 


<!-- Very Complex Statement --> 
<select id="selectBlogDetails" resultMap="detailedBlogResultMap" 


> 


Wn 
D 
pa 
D 
O 
ct 


from 


</select> 


HAApHONnNnNQaQVTVVVVVUVUUVPSrrrrrrwanwnw 


.id as blog_id, 

.title as blog_title, 
.author_id as blog_author_id, 
.id as author_id, 

.username as author_username, 
.password as author_password, 
.email as author_email, 

.bio as author_bio, 
.favourite_section as author_favourite_section, 
.id as post_id, 

.blog_id as post_blog_id, 
.author_id as post_author_id, 
.created_on as post_created_on, 
.section as post_section, 
.subject as post_subject, 
.draft as draft, 

,body as post_body, 

.id as comment_id, 

.post_id as comment_post_id, 
,name as comment_name, 
.comment as comment_text, 

.id as tag_id, 

.hame as tag_name 


Blog B 

left outer join Author A on B.author_id = A.id 
left outer join Post P on B.id = P.blog_id 

left outer join Comment C on P.id = C.post_id 
left outer join Post_Tag PT on PT.post_id = P.id 
left outer join Tag T on PT.tag_id = T.id 

where B.id = #{id} 


可 能 想 把 它 映射 到 一 个 智能 的 对 象 模型 ,包含 一 个 作者 写 的 博客 ,有 很 多 的 博文 ,每 
0 条 的 评论 和 标签 。 下面 是 一 个 完整 的 复杂 结果 映射 例子 (假设 作 
, 博客, 博文 , 评论 和 标签 都 是 类 型 的 别名 ) 我 们 来 看 看 ，。 但 是 不 用 紧张 , 我 们 会 
步 一 步 来 说 明 。 当天 最 初 它 看 起 来 令 人 生 蛙 ,但 实际 上 非常 简单 。 


<!-- Very Complex Result Map --> 
<resultMap id="detailedBlogResultMap" type="Blog"> 
<constructor> 
<idArg column="blog_id" javaType="int"/> 
</constructor> 
<result property="title" column="blog_title"/> 
<association property="author" javaType="Author"> 
<id property="id" column="author_id"/> 
<result property="username" column="author_username"/> 
<result property="password" column="author_password"/> 
<result property="email" column="author_email"/> 
<result property="bio" column="author_bio"/> 
<result property="favouriteSection" column="author_favourite 
_section"/> 
</association> 
<collection property="posts" ofType="Post"> 
<id property="id" column="post_id"/> 
<result property="Subject" column="post_subject"/> 
<association property="author" javaType="Author"/> 
<collection property="comments" ofType="Comment"> 
<id property="id" column="comment_id"/> 
</collection> 
<collection property="tags" ofType="Tag" > 
<id property="id" column="tag_id"/> 
</collection> 
<discriminator javaType="int" column="draft"> 
<case value="1" resultType="DraftPost"/> 
</discriminator> 
</collection> 
</resultMap> 


resultMap 元 素 有 很 多 子 元 素 和 一 个 值得 讨论 的 结构 。 下 面 是 resultMap 元 素 的 概 
念 视图 


resultMap 


e constructor -类 在 实例 化 时 ,用 来 注入 结果 到 构造 方法 中 
o idArg -ID 参数 ;标记 台 2 ee 整体 效能 


o arg -注入 到 构造 方法 的 一 结果 

id 一 一 个 1D #4122 ee ID 人 整体 效能 
result 一 注入 到 字段 或 JavaBean 属性 的 普通 结果 
association 一 一 个 复杂 的 类 型 关联 ;许多 2 包 成 这 种 类 型 


o HA RRA — 结果 映射 自身 的 关联 ,或 者 参考 一 个 
e collection 一 复杂 类 型 的 集 
o 诅 入 结果 映射 一 结果 映射 自身 的 集 ,或 者 参考 一 个 
e discriminator 一 使 用 结果 值 来 决定 使 用 哪个 结果 映射 
o case 一 基于 某 SR DRA 
m KARR — 这 种 情形 结果 也 映射 它 本身 , 因 此 可 以 包含 很 多 相 同 


的 元 素 ,或 者 它 可 以 参照 一 个 外 部 的 结果 映射 
ResultMap Attributes 


Attribute Description 


jd Aunidue identifier in this namespace that can be used to 
reference this result map. 
A fully qualified Java class name, or a type alias (see the 


t 
ME table above for the list of built-in type aliases). 


If present, MyBatis will enable or disable the automapping 
autoMapping for this ResultMap. This attribute overrides the global 
autoMappingBehavior. Default: unset. 


最 佳 实践 UHR TERRA o BUM AA) AE HB EK o d RRRA E 
一 次 创建 一 个 向 上 面 示 例 那 样 的 丐 大 的 结果 映射 , 那么 可 能 会 有 错误 而 且 很 难 去 控 
制 它 RLM © 。 开 始 简单 一 些 ,一 步 一 步 的 发 展 。 而 且 要 进行 单元 测试 ! 使 用 该 框架 的 
缺点 是 它们 有 时 是 墨盒 (是 否 可 见 源 代 码 ) o 你 确定 你 实现 想 要 的 行为 的 最 好 选择 是 
编 写 单元 测试 。 它 也 可 以 你 帮助 得 到 提交 时 的 错误 。 


下 面 一 部 分 将 详细 说 明 每 个 元 素 。 


id & result 


<id property="id" column="post_id"/> 
<result property="Subject" column="post_subject"/> 


这 些 是 结果 映射 最 基本 内 容 。id 和 result 都 映射 一 个 单独 列 的 值 到 简单 数据 类 型 ( 字 
F 串 , 整 型 , 双 精 度 浮 点 数 ,日 期 等 ) 的 单独 属性 或 字段 。 


这 两 者 之 间 的 唯一 不 同 是 id 表示 的 结果 将 是 当 比较 对 象 实例 时 用 到 的 标识 属性 。 
帮 助 来 改进 整体 表现 ,特别 是 缓存 和 点 入 结果 映射 (也 就 是 联合 映射 ) 。 


每 个 都 有 一 些 属性 : 
Id and Result Attributes 


ue 


属性 


property 


column 


javaType 


jdbcType 


typeHandler 


描述 


映射 到 列 结果 的 字段 或 属性 。 如 果 匹 配 的 是 存在 的 ,和 给 
称 相同 的 JavaBeans 的 属性 ,那么 就 会 使 有 用。 否则 o 
将 会 寻找 给 定名 称 property 的 字段 。 这 两 种 情形 你 可 以 使 用 
通常 点 式 的 复杂 属性 导航 。 比 如 ,你 可 以 这 样 映射 一 些 东 西 : 
“username”, 或 者 映射 到 一 些 复杂 的 东西 : 
“address.street.number” ° 


从 数据 库 中 得 到 的 列 名 ,或 者 是 列 名 的 重 命名 标签 。 这 也 是 通 
常 和 会 传递 给 resultSet.getString(columnName) 方 法 参数 中 
48 Fe] a A Bo 


一 个 Java 类 的 完全 限定 名 ,或 一 个 类 型 别名 (参考 上 面 内 建 类 
型 别名 的 列表 ) 。 如 果 你 映射 到 一 个 JavaBean,MyBatis 通 
常 可 以 断定 类 型 。 然而 ,如 果 你 映射 到 的 是 HashMap, 那 么 你 
应 该 明确 地 指定 javaType 来 保证 所 需 的 行为 。 


在 这 个 表格 之 后 的 所 支持 的 JDBC 类 型 列表 中 的 RA o 
JDBC 类 型 是 仅 仅 需 有 要 对 插入 ， 更 新 和 删除 操作 可 能 为 空 的 
列 进 行 处 理 。 这 是 JDBC jdbcType 的 需要 ,而 不 是 MyBatis 
的 。 如 果 你 直接 使 用 JDBC 编程 ,你 需要 指定 这 个 类 型 -但 仅 
仅 对 可 能 为 空 的 值 。 

我 们 在 前 面 讨论 过 默认 的 类 型 处 理 器 。 使 用 这 个 属性 ,你 可 以 
履 盖 黑 认 的 类 型 处 理 器 。 这 个 属性 值 是 类 的 完全 限定 名 或 者 
是 一 个 类 型 处 理 器 的 实现 ,或 者 是 类 型 别名 。 


支持 的 JDBC 类 型 


为 了 未 来 的 参考 ,MyBatis 通过 包含 的 jdbcType 枚 举 型 ,支持 下 面 的 JDBC 类 型 。 


BIT FLOAT CHAR TIMESTAMP OTHER 
TINYINT REAL VARCHAR BINARY BLOG 
SMALLINT DOUBLE LONGVARCHAR VARBINARY CLOB 
INTEGER NUMERIC DATE LONGVARBINARY BOOLEAN 
BIGINT DECIMAL TIME NULL CURSOR 
构造 方法 
<constructor> 


<idArg column="id" javaType="int"/> 
<arg column="username" javaType="String"/> 


</constructor> 


对 于 大 多 数 数 据 传输 对 象 (Data Transfer Object,DTO) 类 型 ,属性 可 以 起 作用 ,而 且 像 
你 绝 大 多 数 的 领域 模型 ,指令 也 许 是 你 想 使 用 一 成 不 变 的 类 的 地 方 。 通常 包含 引用 
或 查询 数 据 的 表 很 少 或 基本 不 变 的 话 对 一 成 不 变 的 类 来 说 是 合适 的 。 构造 方法 注 
入 允许 你 在 初始 化 时 为 类 设置 属性 的 值 ,而 不 用 暴露 出 公有 方法 。MyBatis 也 支持 私 
有 属性 和 私有 JavaBeans 属 性 来 达到 这 个 目的 ,但 是 一 些 人 更 青睐 构造 方法 注入 。 
构造 方法 元 素 支 持 这 个 。 


看 看 下 面 这 个 构造 方法 : 


public class User { 
和 
public User(int id, String username) { 
a ae 


} 
JV/ 


} 


为 了 向 这 个 构造 方法 中 注入 结果 ,MyBatis 需要 通过 它 的 参数 的 类 型 来 标识 构造 方 
eo Java 没有 自 查 (反射 ) 参 数 名 的 方法 。 所 以 当 创建 一 个 构造 方法 元 素 时 ,保证 参 
数 是 按 顺序 排列 的 ,而 且 数 据 类 型 也 是 确定 的 。 


<Constructor> 

<idArg column="id" javaType="int"/> 

<arg column="username" javaType="String"/> 
</constructor> 


剩余 的 属性 和 规则 和 固定 的 id 和 result 元 素 是 相同 的 。 


属性 描述 
来 自 数据 库 的 类 名 ,或 重 命名 的 列 标签 。 这 和 通常 传递 给 


ill 、 > A 由 日 = 
ERSEN resultSet.getString(columnName) 方 法 的 字符 串 是 相同 的 。 
一 个 Java 类 的 完全 限定 名 ,或 一 个 类 型 别名 (参考 上 面 内 建 类 
ane 型 别名 的 列表 )。 如 果 你 映射 到 一 个 JavaBean,MyBatis 通 


常 可 以 断定 类 型 。 然 而 ,如 果 你 映射 到 的 是 HashMap, 那 么 你 
应 该 明确 地 指定 javaType 来 保证 所 需 的 行为 。 


在 这 个 表格 之 前 的 所 支持 的 JDBC 类 型 列表 中 的 类 型 。 
JDBC 类 型 是 仅仅 需要 对 插入 , 更 新 和 删除 操作 可 能 为 空 的 

jdbcType 列 进行 处 理 。 这 是 JDBC 的 需要 , jdbcType 而 不 是 MyBatis 
的 。 如 果 你 直接 使 用 JDBC 编程 ,你 需要 指定 这 个 类 型 -但 仅 
仅 对 可 能 为 空 的 值 。 


我 们 在 前 面 讨论 过 默认 的 类 型 处 理 器 。 使 用 这 个 属性 ,你 可 以 
typeHandler 覆盖 默认 的 类 型 处 理 器 。 这 个 属性 值 是 类 的 完全 限定 名 或 
者 是 一 个 类 型 处 理 器 的 实现 , 或 者 是 类 型 别名 。 


The ID of another mapped statement that will load the 
complex type required by this property mapping. The 
select values retrieved from columns specified in the column 
attribute will be passed to the target select statement as 
parameters. See the Association element for more. 


This is the ID of a ResultMap that can map the nested 
results of this argument into an appropriate object graph. 
This is an alternative to using a call to another select 
statement. It allows you to join multiple tables together into 
a single ResultSet .Sucha ResultSet will contain 


区 duplicated, repeating groups of data that needs to be 
decomposed and mapped properly to a nested object 
graph. To facilitate this, MyBatis lets you "chain" result 
maps together, to deal with the nested results. See the 
Association element below for more. 


<association property="author" column="blog_author_id" javaType= 
"Author"> 

<id property="id" column="author_id"/> 

<result property="username" column="author_username"/> 
</association> 


关联 元 素 处 理 *“ 有 一 个 "类 型 的 关系 。 比 如 ,在 我 们 的 示例 中 ,一 个 博客 有 一 个 用 户 。 
关联 映射 就 工作 于 这 种 结果 之 上 。 你 指定 了 目标 属性 ,来 获取 值 的 列 ,属性 的 java 类 
型 (很 多 情况 下 MyBatis 可 以 自己 算出 来 ) ,如 果 需 要 的 话 还 有 jdbc KA wR RER 


盖 或 获取 的 结果 值 还 需要 类 型 控制 器 。 


关联 中 不 同 的 是 你 需要 告诉 MyBatis 如 何 加 载 关联 。MyBatis 在 这 方面 会 有 两 种 不 


同 的 方式 : 


e 瞬 套 查询 :通过 执行 另外 一 个 SQL 映射 语句 来 返回 预期 的 复杂 类 型 。 
e 瞬 套 结果 :使 用 远 套 结果 映射 来 处 理 重 复 的 联合 结果 的 子 集 。 首 先 , 然 让 我 们 来 
查看 这 个 元 素 的 属性 。 所 有 的 你 都 会 看 到 , 它 和 普通 的 只 由 select 和 


resultMap 属性 的 结果 映射 不 同 。 


属性 


property 


javaType 


jdbcType 


typeHandler 


RERMREBG 


描述 


映射 到 列 结果 的 字段 或 属性 。 如 果 匹 配 的 是 存在 的 ,和 给 定名 
称 相同 的 property JavaBeans 的 属性 , 那么 就 会 使 用 。 否则 
MyBatis 将 会 寻找 给 定名 称 的 字段 。 这 两 种 情形 你 可 以 使 用 
通常 点 式 的 复杂 属性 导航 。 比 如 ,你 可 以 这 样 映 射 一 些 东 西 
:“ username ”或 者 映射 到 一 些 复 杂 的 东西 : 
“address.street.number” ° 


一 个 Java 类 的 完全 限定 名 ,或 一 个 类 型 别名 (参考 上 面 内 建 类 
型 别名 的 列 RK) 。 如 果 你 映射 到 一 个 JavaBean,MyBatis 通 
常 可 以 断定 类 型 。 然 而 ,如 javaType 果 你 映射 到 的 是 
HashMap, 那 么 你 应 该 明确 地 指定 javaType 来 保证 所 需 的 行 
P 


在 这 个 表格 之 前 的 所 支持 的 JDBC 类 型 列表 中 的 类 型 。 
JDBC 类 型 是 仅仅 需要 对 插入 , 更 新 和 删除 操作 可 能 为 空 的 
列 进行 处 理 。 这 是 JDBC 的 需要 , jdbcType 而 不 是 MyBatis 
的 。 如 果 你 直接 使 用 JDBC 编程 ,你 需要 指定 这 个 类 型 -但 仅 
仅 对 可 能 为 空 的 值 。 

我 们 在 前 面 讨 论 过 默认 的 类 型 处 理 器 。 使 用 这 个 属性 ,你 可 以 
覆盖 默认 的 typeHandler 类 型 处 理 器 。 这 个 属性 值 是 类 的 完 
全 限定 名 或 者 是 一 个 类 型 处 理 器 的 实现 , 或 者 是 类 型 别名 。 


属性 描述 


来 自 数据 库 的 类 名 ,或 重 命名 的 列 标签 。 这 和 通常 传递 给 
resultSet.getString(columnName) 方 法 的 字符 串 是 相同 的 。 
coum 注意 :要 处 理 复 合 主键 ,你 可 以 指定 多 个 列 名 
通 过 column=” {prop1=col1,prop2=col2} ”这 种 语法 来 传递 给 
诅 套 查询 语 ao RAF prop1 和 prop2 以 参数 对 象形 式 来 
kB 2 A RARER 4) © 


另外 一 个 映射 语句 的 |D, 可 以 加 载 这 个 属性 映射 需要 的 复杂 类 
型 。 获 取 的 在 列 属 性 中 指定 的 列 的 值 将 被 传递 给 目标 select 语 
多 作为 参数 。 表 格 后 面 有 一 个 详细 的 示例 。 select 注意 :要 
select Aes TB MA MU SS + 5 aa 3 column=” 
{prop1=col1,prop2=col2} ” 3% 4p 14 HK Ke AREA 4] © 
这 会 引起 prop1 和 prop2 RAAI ARAARA 
1a) 4% AJ © 
Optional. Valid values are lazy and eager . If present, it 


fetchType supersedes the global configuration parameter 
lazyLoadingEnabled for this mapping. 


column 


示例 : 


<resultMap id="blogResult" type="Blog"> 

<association property="author" column="author_id" javaType="Au 
thor" select="selectAuthor"/> 
</resultMap> 


<select id="SelectBlog" resultMap="blogResult"> 
SELECT * FROM BLOG WHERE ID = #{id} 
</select> 


<select id="SselectAuthor" resultType="Author"> 
SELECT * FROM AUTHOR WHERE ID = #{id} 
</select> 


我 们 有 两 个 查询 语 旬 :一 个 来 加 载 博客 ,另外 一 个 来 加 载 作 者 ,而 且 博 客 的 结果 映射 描 
述 了 “selectAuthor" 语 名 应 该 被 用 来 加 载 它 的 author 属性。 


其 他 所 有 的 属性 将 会 被 自动 加 载 , 假 设 它们 的 列 和 属性 名 相 匹 配 。 


这 种 方式 很 简单 , 但 是 对 于 大 型 数据 集合 和 列表 将 不 会 表现 很 好 。 问题 就 是 我 们 熟 
知 的 “N+1 查询 问题 "。 概 括 地 讲 ,N+1 查询 问题 可 以 是 这 样 引起 的 : 


。 你 执行 了 一 个 单独 的 SQL 语句 来 获取 结果 列表 (就 是 “+1”)。 
o 对 返回 的 每 条 记录 ,你 执行 了 一 个 查询 语句 来 为 每 个 加 载 细 节 ( 就 是 <N”)。 


这 个 问题 会 导致 成 百 上 千 的 SQL 语句 被 执行 。 这 通常 不 是 期 望 的 。 


MyBatis 能 延迟 加 载 这 样 的 查询 就 是 一 个 好 处 ,因此 你 可 以 分 散 这 些 语句 同时 运行 的 
消耗 。 然 而 ,如 果 你 加 载 一 个 列表 ,之 后 迅速 迭代 来 访问 诅 套 的 数据 ,你 会 调用 所 有 的 
延迟 加 载 ,这 样 的 行为 可 能 是 很 粮 糕 的 。 


所 以 还 有 另外 一 种 方法 。 


RIK AR BAER 


属性 


resultMap 


columnPrefix 


notNullColumn 


autoMapping 


描述 


这 是 结果 映射 的 |D, 可 以 映射 关联 的 诅 套 结果 到 一 个 合适 
的 对 象 图 中 。 这 是 一 种 替代 方法 来 调用 另外 一 个 查询 语 
名。 这 允许 你 联合 多 个 表 来 合成 到 resultMap 一 个 单独 的 
结果 集 。 这 样 的 结果 集 可 能 包含 重复 ,数据 的 重复 组 需要 被 
分 解 ,合理 映射 到 一 个 诅 套 的 对 象 图 。 为 了 使 它 变 得 容 

多 ,MyBatis 让 你 " 链 接 " 结 果 映 射 ,来 处 理 误 套 结果 。 一 个 例 
子 会 很 容易 来 仿照 ,这 个 表格 后 面 也 有 一 个 示例 。 


When joining multiple tables, you would have to use 
column alias to avoid duplicated column names in the 
ResultSet. Specifying columnPrefix allows you to map 
such columns to an external resultWap. Please see the 
example explained later in this section. 


By default a child object is created only if at least one of 
the columns mapped to the child's properties is non null. 
With this attribute you can change this behaviour by 
specifiying which columns must have a value so MyBatis 
will create a child object only if any of those columns is 
not null. Multiple column names can be specified using a 
comma as a separator. Default value: unset. 


If present, MyBatis will enable or disable auto-mapping 
when mapping the result to this property. This attribute 
overrides the global autoMappingBehavior. Note that it 
has no effect on an external resultMap, so it is pointless 
to use it with select or resultMap attribute. Default 
value: unset. 


在 上 面 你 已 经 看 到 了 一 个 非常 复杂 的 虞 套 关联 的 示例 。 下 面 这 个 是 一 个 非常 简单 的 
示例 来 说 明 它 如 何 工 作 。 代 蔡 了 执行 一 个 分 离 的 语句 ,我 们 联合 博客 表 和 作者 表 在 


一 起 ,就 像 : 


<select id="selectBlog" resultMap="blogResult"> 


select 
B.id as blog_id, 
B.title as blog_title, 
B.author_id as blog_author_id, 
A.id as author_id, 
A.username as author_username, 
A.password as author_password, 
A.email as author_email, 
A.bio as author_bio 


from Blog B left outer join Author A on B.author_id = A.id 
where B.id = #{id} 
</select> 


注意 这 个 联合 查询 , 以 及 采取 保护 来 确保 所 有 结果 被 唯一 而 且 清晰 的 名 字 来 重 命 
名 。 这 使 得 映射 非常 简单 。 现 在 我 们 可 以 映射 这 个 结果 : 


<resultMap id="blogResult" type="Blog"> 

<id property="id" column="blog_id" /> 

<result property="title" column="blog_title"/> 

<association property="author" column="blog_author_id" javaTyp 
e="Author" resultMap="authorResult"/> 
</resultMap> 


<resultMap id="authorResult" type="Author"> 
<id property="id" column="author_id"/> 
<result property="username" column="author_username"/> 
<result property="password" column="author_password"/> 
<result property="email" column="author_email"/> 
<result property="bio" column="author_bio"/> 
</resultMap> 


在 上 面 的 示例 中 你 可 以 看 到 博客 的 作者 关联 代表 着 “authorResult* 结 果 映 射 来 加 载 作 
者 实例 。 


非常 重要 : ARERR YP id 元 素 扮演 了 非常 重要 的 角色 。 应 应 该 通常 指定 一 
个 或 多 个 属性 ,它们 可 以 用 来 唯一 标识 结果 。 实 际 上 就 是 如 果 你 离开 她 了 ,但 是 有 一 
个 严重 的 性 能 问题 时 MyBatis 仍然 可 以 工作 。 选 择 的 属性 越 少 越 好 ,它们 可 以 唯一 
地 标识 结果 。 主 键 就 是 一 个 显而易见 的 选择 (尽管 是 联合 主键 ) 。 


现在 ,上 面 的 示例 用 了 外 部 的 结果 映射 元 素来 映射 关联 。 这 使 得 Author 结果 映射 可 

以 重用 。 然 而 ,如 果 你 不 需要 重用 它 的 话 ,或 者 你 仅仅 引用 你 所 有 的 结果 映射 合 到 一 

个 单独 描 述 的 结果 映射 中 。 你 可 以 褒 套 结果 映射 。 这 里 给 出 使 用 这 种 方式 的 相同 示 
例 : 


<resultMap id="blogResult" type="Blog"> 
<id property="id" column="blog_id" /> 
<result property="title" column="blog_title"/> 
<association property="author" javaType="Author"> 
<id property="id" column="author_id"/> 
<result property="username" column="author_username"/> 
<result property="password" column="author_password"/> 
<result property="email" column="author_email"/> 
<result property="bio" column="author_bio"/> 
</association> 
</resultMap> 


What if the blog has a co-author? The select statement would look like: 


<select id="selectBlog" resultMap="blogResult"> 


select 
B.id as blog_id, 
B.title as blog_title, 
A.id as author_id, 
A.username as author_username, 
A.password as author_password, 
A.email as author_email, 
A.bio as author_bio, 
CA.id as co_author_id, 
CA.username as co_author_username, 
CA.password as co_author_password, 
CA.email as co_author_email, 
CA.bio as co_author_bio 

from Blog B 


left outer join Author A on B.author_id = A.id 
left outer join Author CA on B.co_author_id = CA.id 
where B.id = #{id} 

</select> 


Recall that the resultMap for Author is defined as follows. 


<resultMap id="authorResult" type="Author"> 
<id property="id" column="author_id"/> 
<result property="username" column="author_username"/> 
<result property="password" column="author_password"/> 
<result property="email" column="author_email"/> 
<result property="bio" column="author_bio"/> 
</resultMap> 


Because the column names in the results differ from the columns defined in the 
resultMap, you need to specify columnPrefix to reuse the resultMap for 
mapping co-author results. 


<resultMap id="blogResult" type="Blog"> 
<id property="id" column="blog_id" /> 
<result property="title" column="blog_title"/> 
<association property="author" 
resultMap="authorResult" /> 
<association property="coAuthor" 
resultMap="authorResult" 
columnPrefix="co_" /> 
</resultMap> 


上 面 你 已 经 看 到 了 如 何 处 理 * 有 一 个 "类 型 关 联 。 但 是 * 有 很 多 个 "是 怎样 的 ?下 面 这 个 
部 分 就 是 来 讨论 这 个 主题 的 。 


集合 


<collection property="posts" ofType="domain.blog.Post"> 
<id property="id" column="post_id"/> 
<result property="Subject" column="post_subject"/> 
<result property="body" column="post_body"/> 
</collection> 


集合 元 素 的 作用 几乎 和 关联 是 相同 的 。 实 际 上 ,它们 也 很 相似 ,文档 的 异同 是 多 余 
的 。 所 以 我 们 更 多 关注 于 它们 的 不 同 。 


我 们 来 继续 上 面 的 示例 ,一 个 博客 只 有 一 个 作者 。 但 是 博客 有 很 多 文章 。 在 博客 类 
中 , 这 可 以 由 下 面 这 样 的 写法 来 表示 : 


private List<Post> posts; 


BURA RKEBRRS FE List 中 ,我 们 使 用 集合 元 素 。 就 像 关联 元 素 一 样 ,我 们 可 以 从 
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<resultMap id="blogResult" type="Blog"> 

<collection property="posts" javaType="ArrayList" column="id" 
ofType="Post" select="selectPostsForBlog"/> 
</resultMap> 


<select id="selectBlog" resultMap="blogResult"> 
SELECT * FROM BLOG WHERE ID = #{id} 
</select> 


<select id="SselectPostsForBlog" resultType="Blog"> 
SELECT * FROM POST WHERE BLOG_ID = #{id} 
</select> 


这 里 你 应 该 注意 很 多 东西 ,但 大 部 分 代码 和 上 面 的 关联 元 素 是 非常 相似 的 。 首 先 ,你 
应 该 注意 我 们 使 用 的 是 集合 元 素 。 然 后 要 注意 那个 新 的 “ofType” 属 性 。 这 个 属性 用 
来 区 分 JavaBean( 或 字段 ) 属 性 类 型 和 集合 包含 的 类 型 来 说 是 很 重要 的 。 所 以 你 可 以 
读 出 下 面 这 个 映射 : 


<collection property="posts" javaType="ArrayList" column="id" of 
Type="Post" select="selectPostsForBlog"/> 


ik VE: “te Post 类 型 的 ArrayList 中 的 posts 的 集合 。” 


javaType 属性 是 不 需要 的 ,因为 MyBatis 在 很 多 情况 下 会 为 你 算出 来 。 所 以 你 可 以 
缩短 写法 : 


<collection property="posts" column="id" ofType="Post" select="s 
electPostsForBlog"/> 


eS AR EER 


至 此 ,你 可 以 猜测 集合 的 肯 套 结果 是 如 何 来 工作 的 ,因为 它 和 关联 完全 相同 ,除了 它 应 
用 了 一 个 “ofType" 属 性 


First, let's look at the SQL: 


<select id="selectBlog" resultMap="blogResult"> 
select 
B.id as blog_id, 

.title as blog_title, 

.author_id as blog_author_id, 

.id as post_id, 

.subject as post_subject, 
P.body as post_body, 
from Blog B 
left outer join Post P on B.id = P.blog_id 
where B.id = #{id} 

</select> 
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我 们 又 一 次 联合 了 博客 表 和 文章 表 , 而 且 关 注 于 保证 特性 ,结果 列 标签 的 简单 映射 。 
现 在 用 文章 映射 集合 映射 博客 ,可 以 简单 写 为 : 


<resultMap id="blogResult" type="Blog"> 
<id property="id" column="blog_id" /> 
<result property="title" column="blog_title"/> 
<collection property="posts" ofType="Post"> 
<id property="id" column="post_id"/> 
<result property="Subject" column="post_subject"/> 
<result property="body" column="post_body"/> 
</collection> 
</resultMap> 


同样 ,要 记得 id 元素 的 重要 性 ,如 果 你 不 记得 了 ,请 阅读 上 面 的 关联 部 分 。 


同样 , 如 果 你 引用 更 长 的 形式 允许 你 的 结果 映射 的 更 多 重用 , 你 可 以 使 用 下 面 这 个 替 
代 的 映射 : 


<resultMap id="blogResult" type="Blog"> 

<id property="id" column="blog_id" /> 

<result property="title" column="blog_title"/> 

<collection property="posts" ofType="Post" resultMap="blogPost 
Result" columnPrefix="post_"/> 
</resultMap> 


<resultMap id="blogPostResult" type="Post"> 
<id property="id" column="id"/> 
<result property="Subject" column="subject"/> 
<result property="body" column="body"/> 
</resultMap> 


注意 这 个 对 你 所 映射 的 内 容 没有 深度 ,广度 或 关联 和 和 集合 相 联合 的 限制 。 当 映射 它 
们 时 你 应 该 在 大 脑 中 保留 它们 的 表现 。 你 的 应 用 在 找到 最 佳 方法 前 要 一 直 进 行 的 
单元 测试 和 性 能 测试 。 好 在 myBatis 让 你 后 来 可 以 改变 想法 ,而 不 对 你 的 代码 造成 


很 小 (或 任何 ) 影 响 。 


高 级 关联 和 集合 映射 是 一 个 深度 的 主题 。 文 档 只 能 给 你 介绍 到 这 了 。 加 上 一 点 联系 ， 
你 会 很 快 清楚 它们 的 用 法 。 


<discriminator javaType="int" column="draft"> 
<case value="1" resultType="DraftPost"/> 
</discriminator> 


有 时 一 个 单独 的 数据 库 查 询 也 许 返回 很 多 不 同 (但 是 希望 有 些 关联 ) 数据 类 型 的 结果 
集 。 鉴 别 器 元 素 就 是 被 设计 来 处 理 这 个 情况 的 , 还 有 包括 类 的 继承 层次 结构 。 鉴别 
器 非常 容易 理 解 ,因为 它 的 表现 很 像 Java 语言 中 的 switch 7 4 © 


定义 鉴别 器 指定 了 column 和 javaType 属性 。 列 是 MyBatis 查找 比较 值 的 地 方 。 
JavaType 是 需要 被 用 来 保证 等 价 测试 的 合适 类 型 (尽管 字符 串 在 很 多 情形 下 都 会 有 
用 )。 比 如 : 


<resultMap id="vehicleResult" type="Vehicle"> 
<id property="id" column="id" /> 
<result property="vin" column="vin"/> 
<result property="year" column="year"/> 
<result property="make" column="make"/> 
<result property="model" column="model"/> 
<result property="color" column="color"/> 
<discriminator javaType="int" column="vehicle_type"> 
<case value="1" resultMap="carResult"/> 
<case value="2" resultMap="truckResult"/> 
<case value="3" resultMap="vanResult"/> 
<case value="4" resultMap="SuvResult"/> 
</discriminator> 
</resultMap> 


在 这 个 示例 中 , MyBatis 会 从 结果 集中 得 到 每 条 记录 , 然后 比较 它 的 vehicle 类 型 的 
值 。 如 果 它 匹配 任何 一 个 鉴别 器 的 实例 ,那么 就 使 用 这 个 实例 指定 的 结果 映射 。 换 
句 话说, 这样 做 完全 是 剩余 的 结果 映射 被 忽略 (除非 它 被 扩展 ,这 在 第 二 个 示例 中 讨 
论 )。 如 果 没 有 任何 一 个 实例 相 匹配 ,那么 MyBatis 仅仅 使 用 鉴别 器 块 外 定义 的 结果 
映射 。 所 以 ,如 果 carResult 按 如 下 声明 : 


<resultMap id="carResult" type="Car"> 
<result property="doorCount" column="door_count" /> 
</resultMap> 


那么 只 有 doorCount 属性 会 被 加 载 。 这 步 完成 后 完 整地 允许 鉴别 器 实例 的 独立 组 ， 
尽管 和 父 结 果 上 映射 可 能 没有 什么 关系 。 这 种 情况 下 ,我 们 当然 知道 cars 和 vehicles 
之 间 有 关系 ,如 Car 是 一 个 Vehicle 实例 。 因此 ,我 们 起 要 剩余 的 属性 也 被 加 载 。 我 
们 设置 的 乡 吉 果 映射 的 简单 改变 如 下 。 


<resultMap id="carResult" type="Car" extends="vehicleResult"> 
<result property="doorCount" column="door_count" /> 
</resultMap> 


现在 vehicleResult 和 carResult 的 属性 都 会 被 加 载 了 。 


尽管 曾经 有 些 人 会 发 现 这 个 外 部 映射 定义 会 多 少 有 一 些 令 人 厌烦 之 处 。 因此 还 有 另 
外 一 种 语法 来 做 简洁 的 映射 风格 。 比 如 : 


<resultMap id="vehicleResult" type="Vehicle"> 
<id property="id" column="id" /> 
<result property="vin" column="vin"/> 
<result property="year" column="year"/> 
<result property="make" column="make"/> 
<result property="model" column="model"/> 
<result property="color" column="color"/> 
<discriminator javaType="int" column="vehicle_type"> 
<case value="1" resultType="carResult"> 
<result property="doorCount" column="door_count" /> 
</case> 
<case value="2" resultType="truckResult"> 
<result property="boxSize" column="box_size" /> 
<result property="extendedCab" column="extended_cab" /> 
</case> 
<case value="3" resultType="vanResult"> 
<result property="powerSlidingDoor" column="power_sliding_ 
door" /> 
</case> 
<case value="4" resultType="SuvResult"> 
<result property="allwheelDrive" column="all_wheel_drive" 
/> 
</case> 
</discriminator> 
</resultMap> 


要 记得 这 些 都 是 结果 映射 , 如 果 你 不 指定 任何 结果 , ABA MyBatis 将 会 为 你 自动 匹 
配 列 和 属性 。 所 以 这 些 例 子 中 的 大 部 分 是 很 兄长 的 ,而 其 实 是 不 需要 的 。 也 就 是 说 ， 
很 多 数据 库 是 很 复杂 的 ,我 们 不 太 可 能 对 所 有 示例 都 能 依靠 它 。 


自动 映射 


正如 你 在 前 面 一 节 看 到 的 ， ee La cba cte am 
果 。 如果 遇 到 复杂 的 场景 ， 你 需要 构建 一 个 result map。 但 是 在 本 节 你 将 看 到 ， 
也 可 以 混合 使 用 这 两 种 策略 。 让 我 们 到 深 一 点 的 层面 上 看 看 自 eee any 
的 。 


当 自 动 映 射 查询 结果 时 ，MyBatis 会 获取 Sql 返回 的 列 名 并 在 java 类 中 查找 相同 名 字 
的 属性 (忽略 大 小 写 ) 。 这 意味 着 如 果 Mybatis 发 现 了 /D 列 和 ja 属性 ，Mybatis 会 
将 |D 的 值 赋 给 jd 。 


通常 数据 库 列 使 用 大 写 单词 命名 ， 单 词 间 用 下 划 线 分 隔 ; 而 java 属 性 一 般 遵 循 驼峰 
命名 法 。 为 了 在 这 两 种 全 命名 方式 之 间 启 用 自动 映射 ， 需要 将 


mapUnderscoreToCamelCase 设置 为 true。 


自动 映射 甚至 在 特定 的 result map 下 也 能 工作 。 在 这 种 情况 下 ， 对 于 每 一 个 result 
map, 所 有 的 ResultSet 提 供 的 列 ， 如果 没 有 被 手工 映射 ， 则 将 被 自动 映射 。 自 动 映 
射 处 理 完毕 后 手工 映射 才 会 被 处 理 。 在 接 下 来 的 例子 中 ，ja 和 userName 列 将 被 
自动 映射 ，hashea passwora 列 将 根据 配置 映射 。 


<select id="selectUsers" resultMap="userResultMap"> 


select 
user_id as edie 
user_name as "userName", 


hashed_password 
from some_table 
where id = #{id} 
</select> 


<resultMap id="userResultMap" type="User"> 
<result property="password" column="hashed_password"/> 
</resultMap> 


There are three auto-mapping levels: 


e NONE - disables auto-mapping. Only manually mapped properties will be 
set. 

e PARTIAL - will auto-map results except those that have nested result 
mappings defined inside (joins). 

e FULL -auto-maps everything. 


The default value is PARTIAL , and itis so fora reason. When FULL is used 
auto-mapping will be performed when processing join results and joins retrieve 
data of several different entities in the same row hence this may result in 
undesired mappings. To understand the risk have a look at the following sample: 


<select id="selectBlog" resultMap="blogResult"> 
select 
B.id, 
B.title, 
A.username, 
from Blog B left outer join Author A on B.author_id = A.id 
where B.id = #{id} 
</select> 


<resultMap id="blogResult" type="Blog"> 
<association property="author" resultMap="authorResult"/> 
</resultMap> 


<resultMap id="authorResult" type="Author"> 
<result property="username" column="author_username"/> 
</resultMap> 


With this result map both Blog and Author will be auto-mapped. But note that 
Author has an id property and there is a column named id in the ResultSet so 
Author's id will be filled with Blog's id, and that is not what you were expecting. So 
use the FULL option with caution. 


Regardless of the auto-mapping level configured you can enable or disable the 
automapping for an specific ResultMap by adding the attribute autoMapping to 
it: 


<resultMap id="userResultMap" type="User" autoMapping="false"> 
<result property="password" column="hashed_password"/> 
</resultMap> 


BAG 


MyBatis 包含 一 个 非常 强大 的 查询 缓存 特性 , 它 可 以 非常 方便 地 配置 和 定制 。 
MyBatis 3 中 的 缓存 实现 的 很 多 改进 都 已 经 实现 了 ,使 得 它 更 加 强大 而 且 易 于 配置 。 


默认 情况 下 是 没有 开启 缓存 的 ,除了 局 部 的 session 缓存 ,可 以 增强 变现 而 且 处 理 循 
环 依赖 也 是 必须 的 。 要 开启 二 级 缓存 ,你 需要 在 你 的 SQL 映射 文件 中 添加 一 行 : 


<cache/> 


字面 上 看 就 是 这 样 。 这 个 简单 语句 的 效果 如 下 : 


。 映射 语句 文件 中 的 所 有 select 语句 将 会 被 缓存 。 
。 映射 语句 文件 中 的 所 有 insert,update 和 delete 语句 会 刷新 缓存 。 
e 缓存 会 使 用 Least Recently Used(LRU, 最 近 最 少 使 用 的 ) 算 法 来 收回 。 


o 根据 时 间 表 (比如 no Flush Interval, 没 有 刷新 闻 隔 ), 缓存 不 会 以 任何 时 间 顺 序 
来 刷新 。 

。 人 缓存 会 存储 列表 集合 或 对 象 (无 论 查询 方法 返回 什么 ) 的 1024 个 引用 。 

o 缓存 会 被 视 为 是 read/write( 可 读 / 可 写 ) 的 缓存 ,意味 着 对 象 检 索 不 是 共享 的 ,而 
且 可 以 安全 地 被 调用 者 修改 ,而 不 干扰 其 他 调用 者 或 线程 所 做 的 潜在 修改 。 


所 有 的 这 些 属 性 都 可 以 通过 缓存 元 素 的 属性 来 修改 。 比 如 : 


<Cache 
eviction="FIFO" 
FlushInterval="60000" 
$ize="512" 
readOnly="true"/> 


这 个 更 高 级 的 配置 创建 了 一 个 FIFO BG HAM 60 秒 刷 新 , 存 数 结果 对 象 或 列表 的 
512 个 引用 ,而 且 返 回 的 对 象 被 认为 是 只 读 的 ,因此 在 不 同 线程 中 的 调用 者 之 间 修 改 
它们 会 导致 冲突 。 


可 用 的 收回 策略 有 : 


LRU 二 最 近 最 少 使 用 的 : 移 除 最 长 时 间 不 被 使 用 的 对 象 。 

FIFO 一 先进 先 出 : 按 对 象 进入 缓存 的 顺序 来 移 除 它们 。 

SOFT 一 软 引 用 : 移 除 基于 垃圾 回收 器 状态 和 软 引 用 规则 的 对 象 。 

WEAK 一 弱 引 用 :更 积极 地 移 除 基 于 垃圾 收集 器 状态 和 弱 引 用 规则 的 对 象 。 


默认 的 是 LRU。 


flushlnterval( 刷 新 闻 隔 ) 可 以 被 设置 为 任意 的 正 整数 ,而 且 它 们 代表 一 个 合理 的 毫秒 
形式 的 时 间 段 。 默 认 情 况 是 不 设置 ,也 就 是 没有 刷新 间隔 ,缓存 仅仅 调用 语句 时 刷 
新 。 


Size( 引 用 数目 ) 可 以 被 设置 为 任意 正 整 数 ,要 记 住 你 缓存 的 对 象 数目 和 你 运行 环境 的 
可 用 内 存 资 源 数目 。 上 默认 值 是 1024。 


readOnly( 只 读 ) 属 性 可 以 被 设置 为 true 或 false。 只 读 的 缓存 会 给 所 有 调用 者 返回 缓 
存 对 象 的 相同 实例 。 因 此 这 些 对 象 不 能 被 修改 。 提供 了 很 重要 的 ， 性 能 优势 。 可 读 

写 的 缓存 会 返回 缓存 对 象 的 拷贝 (通过 序列 化 ) 。 这 会 慢 一 些 ,但 是 安全 ,因此 默认 是 

false ° 


使 用 自 定 义 缓存 


这 些 自 定义 缓存 的 方式 , 你 也 可 以 通过 你 自己 的 缓存 或 为 其 他 第 三 方 缓存 
配器 来 完全 敌 盖 缕 存 行为 。 


<cache type="com.domain.something.MyCustomCache"/> 


这 个 示 例 展 RT 如 何 使 用 一 个 自 定义 的 缓 存 实现 。type 属性 指定 的 类 必须 
实现 org.mybatis.cache.Cache 接口 。 这 个 接口 是 MyBatis 框架 中 很 多 复杂 的 接口 
之 一 ,但 是 简单 给 定 它 做 什么 就 行 。 


public interface Cache { 
String getId(); 
int getSize(); 
void putObject(Object key, Object value); 
Object getObject(Object key); 
boolean hasKey(Object key); 
Object removeObject(Object key); 
void clear(); 


要 配置 你 的 缓存 , 简单 和 公有 的 JavaBeans 属性 来 配置 你 的 缓存 实现 , 而 且 是 通过 
cache 元 素来 传递 属性 , 比如 , 下 面 代 码 会 在 你 的 缓存 实现 中 调用 一 个 称 为 
“setCacheFile(String file)” 的 方法 : 


<cache type="com.domain.something.MyCustomCache"> 
<property name="cacheFile" value="/tmp/my-custom-cache.tmp"/> 
</cache> 


你 可 以 使 用 所 有 简单 类 型 作为 JavaBeans 的 属性 ,MyBatis 会 进行 转换 。 


记得 缓存 配置 和 缓存 实例 是 绑 定 在 SQL 映射 文件 的 命名 空间 是 很 重要 的 。 因 此 ,所 
有 在 相同 命名 空间 的 语句 正如 绑 定 的 缓存 一 样 。 语 多 可 以 修改 和 缓存 交互 的 方式 ， 
或 在 语句 的 语句 的 基础 上 使 用 两 种 简单 的 属性 来 完全 排除 它们 。 默 认 情 况 下 ,语句 
可 以 这 样 来 配置 : 


<select ... flushCache="false" useCache="true"/> 
<insert ... flushCache="true"/> 
<update ... flushCache="true"/> 
<delete ... flushCache="true"/> 


为 那些 是 上 默认 的 ,你 明显 不 能 明确 地 以 这 种 方式 来 配置 一 条 语句 。 相 反 , 如 果 你 想 
改 变 默 认 的 行为 ,只 能 设置 flushCache 和 useCache 属性 。 比 如 ,在 一 些 情况 下 你 
也 许 想 排除 从 缓存 中 查询 特定 语句 结果 ,或 者 你 也 许 想 要 一 个 查询 语句 来 刷新 组 
存 。 相 似 地 ,你 也 许 有 一 些 更 新 语 负 依靠 执行 而 不 需要 刷新 缓存 。 


BREA 


回想 一 下 上 一 节 内 容 , 这 个 特殊 命名 空间 的 唯一 缓存 会 被 使 用 或 者 刷新 相同 命名 空 
间 内 的 语 名。 也许 将 来 的 某 个 时 候 ,你 会 想 在 命名 空间 中 共享 相同 的 缓存 配置 和 实 
例 。 在 这 样 的 情况 下 你 可 以 使 用 cache-ref 元 素来 引用 另外 一 个 缓存 。 


<cache-ref namespace="com.someone.application.data.SomeMapper"/> 


动态 SQL 


MyBatis : 强大 特性 之 一 便 是 它 的 动态 SQL。 如 果 你 有 使 用 JDBC 或 其 他 类 似 框架 
的 经 验 ， 你 就 能 体会 到 根据 不 同 条 件 拼接 SQL 语句 有 多 么 痛苦 。 拼 接 的 时 候 要 确 

ER AR AGS 了 必要 的 空格 ， 还 要 注意 省 掉 列 名 列表 最 后 的 过 号 。 利 用 动态 SQL 这 一 

特性 可 以 彻底 摆脱 这 种 痛苦 。 


通常 使 用 动态 SQL 不 可 能 是 独立 的 一 部 分 ,MyBatis 当然 使 用 一 种 强大 的 动态 SQL 
语言 来 改进 这 种 情形 ,这 种 语言 可 以 被 用 在 任意 的 SQL 映射 语句 中 。 


动态 A SQL 元 素 和 使 用 JSTL 或 其 他 类 似 基 于 XML 的 文本 处 理 器 相似 。 在 MyBatis 
之 前 的 版 本 中 ,有 很 多 的 元 素 需 要 来 了 解 。MyBatis 3 大 大 提升 了 它们 ,现在 用 不 到 原 

先 一 半 的 元 素 就 可 以 了 。MyBatis 采用 功能 强大 的 基于 OGNL 的 表达 式 来 消除 其 他 

元 素 。 

if 

choose (when, otherwise) 


trim (where, set) 
foreach 


if 
动态 SQL 通常 要 做 的 事情 是 有 条 件 地 包含 where 子 名 的 一 部 分 。 比 如 : 


<select id="findActiveBlogwithTitleLike" 
resultType="Blog"> 
SELECT * FROM BLOG 
WHERE state = ‘ACTIVE’ 
<if test="title != null"> 
AND title like #{title} 
</if> 
</select> 


这 条 语句 提供 了 一 个 可 选 的 文本 查找 类 型 的 功能 。 如 果 没 有 传 入 “title”， 那 么 所 有 处 
于 “ACTIVE” 状 态 的 BLOG 都 会 返回 ; 反之 若 传 入 了 : ， 那么 就 会 把 模糊 查 

找 'title" 内 容 的 BLOG 结果 返回 〈 就 这 个 例子 而 言 ， 细 心 的 读者 会 发 现 其 中 的 参数 值 
是 可 以 包含 一 些 掩 码 或 通配符 的 ) 。 


如 果 想 可 选 地 通过 “title” 和 “author" 两 个 条 件 搜 索 该 怎么 办 呢 ? 首先， 改变 语句 的 名 
称 让 它 更 具 实 际 意义 ; 然后 只 要 加 入 另 一 个 条 件 即 可 。 


<select id="findActiveBlogLike" 
resultType="Blog"> 
SELECT * FROM BLOG WHERE state = ‘ACTIVE’ 
<if test="title != null"> 
AND title like #{title} 


</if> 
<if test="author != null and author.name != null"> 
AND author_name like #{author.name} 
</if> 
</select> 


choose, when, otherwise 


有 些 时 候 ， 我 们 不 想 用 到 所 有 的 条 件 语 句 ， 而 只 想 从 中 择 其 一 二 。 针 对 这 种 情况 ， 
MyBatis 提供 了 choose 元 素 ， 它 有 点 像 Java 中 的 switch 语句。 


还 是 上 面 的 例子 ， 但 是 这 次 变 为 提供 了 “title" 就 按 “title" 查 找 ， 提 供 了 “author" 就 
按 “author" 查 找 ， 若 两 者 都 没有 提供 ， 就 返回 所 有 符合 条 件 的 BLOG (实际 情况 可 能 
是 由 管理 员 按 一 定 策略 选 出 BLOG 列表 ， 而 不 是 返回 大 量 无 意义 的 随机 结果 ) 。 


<select id="findActiveBlogLike" 
resultType="Blog"> 
SELECT * FROM BLOG WHERE state = ‘ACTIVE’ 
<choose> 
<when test="title != null"> 
AND title like #{title} 
</when> 
<when test="author != null and author.name != null"> 
AND author_name like #{author.name} 
</when> 
<otherwise> 
AND featured = 1 
</otherwise> 
</choose> 
</select> 


trim, where, set 


前 面 几 个 例子 已 经 合宜 地 解决 了 一 个 臭名 昭著 的 动态 SQL 问题 。 现 在 考虑 回 
到 “i 人 PP 示例 ， 这 次 我 们 将 “ACTIVE = 1 也 设置 成 动态 的 条 件 ， 看 看 会 发 生 什 么 。 


<select id="findActiveBlogLike" 
resultType="Blog"> 
SELECT * FROM BLOG 


WHERE 

<if test="state != null"> 
state = #{state} 

</if> 


<if test="title != null"> 
AND title like #{title} 


</if> 
<if test="author != null and author.name != null"> 
AND author_name like #{author.name} 
</if> 
</select> 


SELECT * FROM BLOG 
WHERE 


这 会 导致 查询 失败 。 如 果 仅 仅 第 二 个 条 件 匹 配 又 会 怎样 ? 这 条 SQL 最 终 会 是 这 样 : 


SELECT * FROM BLOG 
WHERE 
AND title like ‘someTitle’ 


这 个 查询 也 会 失败 。 这 个 问题 不 能 简单 的 用 条 件 句 式 来 解决 ， 如 果 你 也 曾经 被 迫 这 
样 写 过 ， 那 么 你 很 可 能 从 此 以 后 都 不 想 再 这 样 去 写 了 。 


MyBatis 有 一 个 简单 的 处 理 ， 这 在 90% 的 情况 下 都 会 有 用 。 而 在 不 能 使 用 的 地 方 ， 
你 可 以 自 定义 处 理 方式 来 令 其 正常 工作 。 一 处 简单 的 修改 就 能 得 到 想 要 的 效果 : 


<select id="findActiveBlogLike" 
resultType="Blog"> 
SELECT * FROM BLOG 


<where> 
<if test="state != null"> 
state = #{state} 
</if> 


<if test="title != null"> 
AND title like #{title} 

</if> 

<if test="author != null and author.name != null"> 
AND author_name like #{author.name} 

</if> 

</where> 
</select> 


where 元 素 知 道 只 有 在 一 个 以 上 的 谎 条 件 有 值 的 ， 博 况 下 才 去 插入 WHERE” 子 句 。 而 
且 ， 若 最 后 的 内 容 是 “AND” 或 “OR” 开头 的 ，Where 元 素 也 知道 如 何 将 他 们 去 除 。 


如 果 where 元 素 没 有 按 正常 套路 出 牌 ， 我 们 还 是 可 以 通过 自 定 义 trim 元 素来 定制 
我 们 想 要 的 功能 。 比 如 ， 和 where 元 素 等 价 的 自 定 义 trim THA : 

<trim prefix="WHERE" prefixOverrides="AND |OR "> 

</trim> 
prefixOverrides Ai & 038 1 F 分 隔 的 文本 序列 (注意 此 例 中 的 空格 也 是 必要 


的 ) o ea RAY Fe a E a 
插入 prefix 属性 中 指定 的 内 容 。 


类 似 的 用 于 动态 更 新 语句 的 解决 方案 叫做 set。set 元 素 可 以 被 用 于 动态 包含 需要 更 
新 的 列 ， 而 使 去 其 他 的 。 比 如 : 


<update id="updateAuthorIfNecessary"> 
update Author 


<set> 
<if test="username != null">username=#{username}, </if> 
<if test="password != null">password=#{password},</if> 
<if test="email != null">email=#{email},</if> 
<if test="bio != null">bio=#{bio}</if> 

</set> 

where id=#{id} 
</update> 


这 里 ，set 元 素 会 动态 前 置 SET KF > ALAHA > AAMT AH 
语 名 之 后 很 可 能 就 会 在 生成 的 赋值 语句 的 后 面 留 下 这 些 过 号 。 


若 你 对 等 价 的 自 定义 trim 元 素 的 样子 感 兴 趣 ， 那 这 就 应 该 是 它 的 真面目 : 


<trim prefix="SET" suffixOverrides=", "> 
</trim> 
注意 这 里 我 们 忽略 的 是 后 组 中 的 值 ， 而 又 一 次 附加 了 前 组 中 的 值 。 


foreach 


动态 SQL 的 另外 一 个 常用 的 必要 操作 是 需要 对 一 个 集合 进行 遍历 ， 通 常 是 在 构建 
IN 条 件 语句 的 时 候 。 上 比如 : 


<select id="selectPostIn" resultType="domain.blog.Post"> 


SELECT * 
FROM POST P 
WHERE ID in 


<foreach item="item" index="index" collection="list" 
open="(" separator="," close=")"> 
#{item} 
</foreach> 
</select> 


foreach 元 素 的 功能 是 非常 强大 的 ， 它 允许 你 指定 一 个 集合 ， 声 明 可 以 用 在 元 素 体 
内 的 集合 项 和 索引 变量 。 它 也 允许 你 指定 开 闭 匹配 的 字符 囊 以 及 在 迭代 中 间 放 置 分 
隔 符 。 这 个 元 素 是 很 智能 的 ， 因 此 它 不 会 偶然 地 附加 多 余 的 分 隔 符 。 


注意 你 可 以 将 一 个 List 实例 或 者 数组 作为 参数 对 象 传 给 MyBatis， 当 你 这 么 做 的 时 
候 ，MyBatis 会 自动 将 它 包装 在 一 个 Map 中 并 以 名 称 为 键 。List 实例 将 会 以 "lisf” 作 
为 键 ， 而 数组 实例 的 键 将 是 “array”。 


到 此 我 们 已 经 完成 了 涉及 XML 配置 文件 和 XML 映射 文件 的 讨论 。 下 一 部 分 将 详细 
探讨 Java API， 这 样 才 能 从 已 创建 的 映射 中 获取 最 大 利益 。 


bind 
bind 元 素 可 以 从 OGNL 表达 式 中 创建 一 个 变量 并 将 其 绑 定 到 上 下 文 。 比 如 : 


<select id="selectBlogsLike" resultType="Blog"> 
<bind name="pattern" value="'%' + _parameter.getTitle() + '%'" 
/> 
SELECT * FROM BLOG 
WHERE title LIKE #{pattern} 
</select> 


Multi-db vendor support 


—~ Ht a. J“ databaseld” = #4) databaseldProvider 对 于 动态 代码 来 说 是 可 用 的 ， 
这 样 就 可 以 根据 不 同 的 数据 库 厂商 构建 特定 的 语句 。 比 如 下 面 的 例子 : 


<insert id="insert"> 
<selectKey keyProperty="id" resultType="int" order="BEFORE"> 


<if test="_databaseId == 'oracle'"> 
select seq_users.nextval from dual 
</if> 
<if test="_databaseId == 'db2'"> 
select nextval for seq_users from sysibm.sysdummy1" 
</if> 
</selectKey> 
insert into users values (#{id}, #{name}) 
</insert> 


动态 SQL 中 可 插 拔 的 脚本 语言 


MyBatis 从 3.2 开始 支持 可 插 拔 的 脚本 语言 ， 因 此 你 可 以 在 插入 一 种 语言 的 驱动 
(language driver) 之 后 来 写 基 于 这 种 语言 的 动态 SQL 查询 。 


可 以 通过 实现 下 面 接口 的 方式 来 插入 一 种 语言 : 


public interface LanguageDriver { 

ParameterHandler createParameterHandler(MappedStatement mapped 
Statement, Object parameterObject, BoundSql boundSql1); 

SqlSource createSqlSource(Configuration configuration, XNode s 
cript, Class<?> parameterType); 

SqlSource createSqlSource(Configuration configuration, String 
script, Class<?> parameterType); 


} 


一 旦 有 了 自 定义 的 语言 驱动 ， 你 就 可 以 在 mybatis-config.xml 文件 中 将 它 设置 为 默 


认 语 言 : 


<typeAliases> 

<typeAlias type="org.sample.MyLanguageDriver" alias="myLanguag 
e"/> 
</typeAliases> 
<settings> 

<setting name="defaultScriptingLanguage" value="myLanguage"/> 
</settings> 


除了 设置 默认 语言 ， 你 也 可 以 针对 特殊 的 语句 指定 特定 语言 ， 这 可 以 通过 如 下 的 
lang 属性 来 完成 : 


<select id="SelectBlog" lang="myLanguage"> 
SELECT * FROM BLOG 
</select> 


或 者 在 你 正在 使 用 的 映射 中 加 上 注解 @Lang 来 完成 : 


public interface Mapper { 
@Lang(MyLanguageDriver.class) 
@Select("SELECT * FROM BLOG") 
List<Blog> selectBlog(); 


} 


注意 可 以 将 Apache Velocity 作为 动态 语言 来 使 用 ， 更 多 细节 请 参考 MyBatis- 
Velocity 项 目 。 

你 前 面 看 到 的 所 有 xml 标签 都 是 默认 MyBatis 语言 提供 的 ， 它 是 由 别名 为 xml 
语言 驱动 器 org.apache.ibatis.scripting.xmltags.XmlLanguageDriver 32 
动 的 。 


Java API 


既然 你 已 经 知道 如 何 配置 MyBatis 和 创建 映射 文件 ,你 就 已 经 准备 好 来 提升 技能 了 。 
MyBatis 的 Java API 就 是 你 收获 你 所 做 的 努力 的 地 方 。 正 如 你 ule | 的 ,和 
JODO eee ee 容易 理解 和 维护 。 
MyBatis 3 已 经 引入 了 很 多 重要 的 改进 来 使 得 SQL 映射 更 加 优秀 。 


应 用 目录 结构 
在 我 们 深入 Java API 之 前 ,理解 关于 目录 结构 的 最 佳 实践 是 很 重要 的 。MyBatis 非 
常 灵 活 , 你 可 以 用 你 自己 的 文件 来 做 几乎 所 有 的 事情 。 但 是 对 于 任 一 框架 , 都 有 一 
些 最 佳 的 方式 。 


让 我 们 看 一 下 典型 应 用 的 目录 结构 : 


/my_application 


/bin 
/devlib 
say fal el `<-- MyBatis *.jar 文 件 在 这 里 。、** 
/src 
/org/myapp/ 
/action 
**/data `<-- MyBatis 配 置 文件 在 这 里 ， 包括 映射 器 类 ， XM 


L 配 置 ， XML 了 映射 文件 。 
/mybatis-config. xml 
/BlogMapper. java 
/BlogMapper. xml 

/model 
/service 
/view 
**/properties `<-- 在 你 XML 中 配置 的 属性 文件 在 这 里 。、** 
/test 
/org/myapp/ 
/action 
/data 
/model 
/service 
/view 
/properties 
/web 
/WEB- INF 
/web. xml 


Remember, these are preferences, not requirements, but others will thank you for 
ne a common directory structure. 


分 内 容 剩 余 的 示例 将 假设 你 使 用 了 这 种 目录 结构 。 


SqlSessions 


使 用 MyBatis 的 主要 Java 接口 就 是 SqlSession。 尽 管 你 可 以 使 用 这 个 接口 执行 命 
令 , 获 取 映 射 器 和 管理 事务 。 我 们 会 讨论 SqlSession 本 身 更 多 ,但 是 首先 我 们 还 是 要 
了 解 如 果 获 取 一 个 SqlSession 实例 。SqlSessions 是 由 SqlSessionFactory 实例 
创建 的 。SqlSessionFactory 对象 包含 创建 SqlSession 实 例 的 所 有 方法 。 
而 SqlSessionFactory 本 身 是 由 SqlSessionFactoryBuilder 创建 的 , 它 可 以 从 XML 
配置 ,注解 或 手动 配置 Java 来 创建 SqlSessionFactory 。 


NOTE When using MyBatis with a dependency injection framework like Spring or 
Guice, SqlSessions are created and injected by the DI framework so you don't 
need to use the SqlSessionFactoryBuilder or SqlSessionFactory and can go 
directly to the SqlSession section. Please refer to the MyBatis-Spring or MyBatis- 
Guice manuals for further info. 


SqlSessionFactoryBuilder 


SqlSessionFactoryBuilder 有 五 个 build() 方 法 ,每 一 种 都 允许 你 从 不 同 的 资源 中 创建 
一 个 SqlSession 实例 。 


SqlSessionFactory build(InputStream inputStream) 
SqlSessionFactory build(InputStream inputStream, String environm 
ent) 

SqlSessionFactory build(InputStream inputStream, Properties prop 
erties) 

SqlSessionFactory build(InputStream inputStream, String env, Pro 
perties props) 

SqlSessionFactory build(Configuration config) 


第 一 种 方法 是 最 常用 的 , 它 使 用 了 一 个 参照 了 XML 文档 或 上 面 讨论 过 的 更 特定 的 
mybatis-config.xml 文件 的 Reader 实例 。 可 选 的 参数 是 environment 和 
properties。 Environment 决定 加 载 哪 种 环境 ,包括 数据 源 和 事务 管理 器 。 比 如 : 


<environments default="development"> 
<environment id="development"> 
<transactionManager type="JDBC"> 


<dataSource type="POOLED"> 
</environment> 
<environment id="production"> 
<transactionManager type="MANAGED"> 
<dataSource type="JNDI"> 


</environment> 
</environments> 


如 果 你 调用 了 一 个 使 用 environment 参数 方 式 的 build 方法 , 那么 MyBatis 将 会 使 
用 configuration 对 象 来 配置 这 个 environment。 当然 , 如 果 你 指定 了 一 个 不 合法 的 
environment, 你 会 得 到 错误 提示 。 如 果 你 调用 了 其 中 之 一 没有 environment 参数 的 
build 方法 , 那么 就 使 用 默认 的 environment( 在 上 面 的 示例 中 就 会 指定 为 
default="development”) ° 


如 果 你 调用 了 使 用 properties 实例 的 方法 ,那么 MyBatis 就 会 加 载 那 些 
properties( 属 性 配置 文件 ) ,并 你 在 你 配置 中 可 使 用 它们 。 那 些 属 性 可 以 用 
${propName} 语 法 形式 多 次 用 在 配置 文件 中 。 


回想 一 下 ,属性 可 以 从 mybatis-config.xml 中 被 引用 ,或 者 直接 指定 它 。 因 此 理解 优先 
级 是 很 重要 的 。 我 们 在 文档 前 面 已 经 提 及 它 了 ,但 是 这 里 要 再 次 重申 : 


如 果 一 个 属性 存在 于 这 些 位 置 ,那么 MyBatis 将 会 按 找 下 面 的 顺序 来 加 载 它 们 : 


e 在 properties 元 素 体 中 指定 的 属性 首先 被 读 取 ， 

e 从 properties 元 素 的 类 路 径 resource 或 url 指定 的 属性 第 二 个 被 读 取 , TAR 
盖 已 经 指定 的 重复 属性 ， 

e 作为 方法 参 数 传递 的 属性 最 后 被 读 取 , 可 以 RAC 经 从 properties 元 素 体 和 
resource/url 属性 中 加 载 的 任意 重复 属性 。 


因此 ,最 高 优先 级 的 属性 是 通过 方法 参数 传递 的 ,之 后 是 resource/url 属性 指定 的 ,最 
后 是 在 properties 元 素 体 中 指定 的 属性 。 


总 结 一 下 ,前 四 个 方法 很 大 程度 上 是 相同 的 ,但 是 由 于 可 以 窗 盖 ,就 允许 你 可 选 地 指定 
environment 和 /或 properties。 这 里 给 出 一 个 从 mybatis-config.xml 文件 创建 
SqlSessionFactory 的 示例 : 


String **resource** = "org/mybatis/builder/mybatis-config.xml"; 
InputStream **inputStream** = Resources.getResourceAsStream(reso 
urce); 

SqlSessionFactoryBuilder **builder** = new SqlSessionFactoryBuil 
der(); 

SqlSessionFactory **factory** = builder.build(inputStream) ; 


注意 这 里 我 们 使 用 了 Resources 工具 类 ,这 个 类 在 org.mybatis.io @ P? ° Resources 
类 正 如 其 名 ,会 帮助 你 从 类 路 径 下 ,文件 系统 或 一 个 web URL 加 载 资源 文件 。 看 一 
下 这 个 类 的 源 代码 或 者 通过 你 的 IDE 来 查看 ,就 会 看 到 一 整套 有 用 的 方法 。 这 里 给 
出 一 个 简 表 : 


URL getResourceURL(String resource) 

URL getResourceURL(ClassLoader loader, String resource) 
InputStream getResourceAsStream(String resource) 

InputStream getResourceAsStream(ClassLoader loader, String resou 
rce) 

Properties getResourceAsProperties(String resource) 

Properties getResourceAsProperties(ClassLoader loader, String re 
source) 

Reader getResourceAsReader (String resource) 

Reader getResourceAsReader(ClassLoader loader, String resource) 
File getResourceAsFile(String resource) 

File getResourceAsFile(ClassLoader loader, String resource) 
InputStream getUrlAsStream(String urlString) 

Reader getUrlAsReader(String urlString) 

Properties getUrlAsProperties(String urlString) 

Class classForName(String className) 


最 后 一 个 build 方法 使 用 了 一 个 Configuration & I ° configuration 类 包含 你 可 能 需 
要 了 解 SqlSessionFactory 实例 的 所 有 内 容 。Configuration 类 对 于 配置 的 自 查 很 有 
用 ,包含 查找 和 操作 SQL 映射 (不 推荐 使 用 ,因为 应 用 正 接收 请 求 )。configuration 类 
有 上 所 有 配置 的 开关 , 这 些 你 已 经 了 解 了 ,只 在 Java API 中 露出 来 。 这 里 有 一 个 简单 的 
示例 ,如 何 手动 配置 configuration 实例 ,然后 将 它 传 递 给 build() 方 法 来 创建 
SqlSessionFactory ° 


DataSource dataSource = BaseDataTest.createBlogDataSource(); 
TransactionFactory transactionFactory = new JdbcTransactionFacto 


ry(); 


Environment environment = new Environment("development", transac 
tionFactory, dataSource); 


Configuration configuration = new Configuration(environment ); 
configuration.setLazyLoadingEnabled(true); 
configuration.setEnhancementEnabled(true) ; 
configuration.getTypeAliasRegistry().registerAlias(Blog.class)j; 
configuration.getTypeAliasRegistry().registerAlias(Post.class); 
configuration.getTypeAliasRegistry().registerAlias(Author.class) 


configuration.addMapper(BoundBlogMapper.class); 
configuration.addMapper(BoundAuthorMapper .class); 


SqlSessionFactoryBuilder builder = new SqlSessionFactoryBuilder ( 


); 


SqlSessionFactory factory = builder.build(configuration); 


现在 你 有 一 个 SqlSessionFactory, 可 以 用 来 创建 SqlSession 实例 。 


SqlSessionFactory 


SqlSessionFactory 有 六 个 方法 可 以 用 来 创建 SqlSession 实例 。 通 常 来 说 ,如 何 决 
定 是 你 选择 下 面 这 些 方法 时 : 


e Transaction (事务 ): 你 想 为 session 使 用 事务 或 者 使 用 自动 提交 (通常 意味 着 很 
多 数据 库 和 /或 JDBC 了 驱动 没有 事务 )? 
。 Connection (连接 ): 你 想 MyBatis 获得 来 自 配置 的 数据 源 的 连接 还 是 提供 你 自 


G 
e Execution (执行 ): 你 想 MyBatis 复 用 预 处 理 语 名 和 /或 批量 更 新 语句 (包括 插入 
和 删除 )? 


重 载 的 openSession() 方 法 签名 设置 允许 你 选择 这 些 可 选中 的 任何 一 个 组 合 。 


SqlSession openSession() 

SqlSession openSession(boolean autoCommit ) 

SqlSession openSession(Connection connection) 

SqlSession openSession(TransactionIsolationLevel level) 
SqlSession openSession(ExecutorType execType, TransactionIsolatio 
nLevel level) 

SqlSession openSession(ExecutorType execType) 

SqlSession openSession(ExecutorType execType, boolean autoCommit 
) 

SqlSession openSession(ExecutorType execType, Connection connect 
ion) 

Configuration getConfiguration(); 


默认 的 openSession() 方 法 没有 参数 , 它 会 创建 有 如 下 特性 的 SqlSession: 


会 开启 一 个 事务 (也 就 是 不 自动 提交 ) 

连接 对 象 会 从 由 活动 环境 配置 的 数据 源 实例 中 得 到 。 
事务 隔离 级 别 将 会 使 用 驱动 或 数据 源 的 默认 设置 。 
预 处 理 语 多 不 会 被 复 用 ,也 不 会 批量 处 理 更 新 。 


这 些 方法 大 都 可 以 自我 解释 的 。 开 启 自动 提交 , “true” 传递 给 可 选 的 autoCommit 
参数 。 提供 自 定 义 的 连接 ,传递 一 个 Connection 实例 给 connection 参数 。 注 意 没 
有 和 履 盖 同时 设置 Connection 和 autoCommit 两 者 的 方法 ,因为 MyBatis 会 使 用 当前 
connection 对 象 提 供 的 设 置 。 MyBatis 为 事务 隔离 级 别 调用 使 用 一 个 Java 枚 举 包 
X 8, 称 为 TransactionlsolationLevel, 否则 它们 按 预 期 的 方式 来 工作 ,并 有 JDBC 支 
持 的 5 级 (NONE,READ UNCOMMITTED,READ_COMMITTED,REPEA 
TABLE_READ,SERIALIZA BLE) 


还 有 一 个 可 能 对 你 来 说 是 新 见 到 的 参数 ,就 是 ExecutorType。 这 个 枚 举 类 型 定义 了 
3 fa: 


e ExecutorType.SIMPLE : 这 个 执行 器 类 型 不 做 特殊 的 事情 。 它 为 每 个 语句 的 
执行 创建 一 个 新 的 预 处 理 语 钉 。 

e ExecutorType.REUSE : 这 个 执行 器 类 型 会 复 用 预 处 理 语 钉 。 

e ExecutorType.BATCH : 这 个 执行 器 会 批量 执行 所 有 更 新 语句 ,如 果 SELECT 
在 它们 中 间 执 行 还 会 标定 它们 是 必须 的 ,来 保证 一 个 简单 并 易于 理解 的 行为 。 


注意 在 SqlSessionFactory 中 还 有 一 个 方法 我 们 没有 提 及 ,就 是 
getConfiguration()。 这 个 方法 会 返回 一 个 Configuration 实例 ,在 运行 时 你 可 以 使 用 
它 来 自 检 MyBatis 的 配置 。 


注意 如 果 你 已 经 使 用 之 前 版 本 MyBatis, 你 要 回忆 那些 session,transaction 和 batch 
都 是 分 离 的 。 现 在 和 以 往 不 同 了 ,这 些 都 包含 在 session 的 范围 内 了 。 你 需要 处 理 分 
开 处 理 事务 或 批量 操作 来 得 到 它们 的 效果 。 


SqlSession 


如 上 面 所 提 到 的 ,SqlSession 实例 在 MyBatis 中 是 非常 强大 的 一 个 类 。 在 这 里 你 会 
发 现 所 有 执行 语 多 的 方法 ,提交 或 回 滚 事务 ,还 有 获取 映射 器 实例 。 


在 SqlSession 类 中 有 超过 20 个 方法 ,所 以 将 它们 分 开 成 易于 理解 的 组 合 。 
语句 执行 方法 


这 些 方法 被 用 来 执行 定义 在 SQL 映射 的 XML 文件 中 的 SELECT,INSERT,UPDAE 
T 和 DELETE 语句 。 它 们 都 会 自行 解释 ,每 一 名 都 使 用 语句 的 ID 属性 和 参数 对 象 ， 
参数 可 以 是 原生 类 型 (自动 装 箱 或 包装 类 ) ,JavaBean,POJO 或 Map。 


<T> T selectOne(String statement, Object parameter) 

<E> List<E> selectList(String statement, Object parameter ) 

<K, V> Map<K,V> selectMap(String statement, Object parameter, Str 
ing mapKey) 

int insert(String statement, Object parameter) 

int update(String statement, Object parameter) 

int delete(String statement, Object parameter) 


selectOne 和 selectList 的 不 同 仅 仅 是 selectOne 必须 返回 一 个 对 象 。 如 果 多 余 一 
个 , 或 者 没有 返回 (或 返回 了 null) 那么 就 会 抛 出 异常 。 , 如 果 你 不 知道 需要 多 少 对 
象 , 使 用 selectList ° 


如 果 你 想 检 查 一 个 对 象 是 否 存在 ,那么 最 好 返回 统计 数 (0 或 1) 。 因 为 并 不 是 所 有 语 
JAE 要 参数 ,这 些 方法 都 是 有 不 同 重 载 版 本 的 ,它们 可 以 不 需要 参数 对 象 。 


<T> T selectOne(String statement) 

<E> List<E> selectList(String statement) 

<K, V> Map<K,V> selectMap(String statement, String mapKey) 
int insert(String statement) 

int update(String statement) 

int delete(String statement) 


最 后 ,还 有 查询 方法 的 三 个 高 级 版 本 ,它们 允许 你 限制 返回 行 数 的 范围 ,或 者 提供 自 定 
义 结果 控制 逻辑 ,这 通常 用 于 大 量 的 数据 集合 。 


<E> List<E> selectList (String statement, Object parameter, RowB 
ounds rowBounds) 

<K, V> Map<K,V> selectMap(String statement, Object parameter, Str 
ing mapKey, RowBounds rowbounds) 

void select (String statement, Object parameter, ResultHandler<T 
> handler) 

void select (String statement, Object parameter, RowBounds rowBo 
unds, ResultHandler<T> handler) 


RowBounds 参数 会 告诉 MyBatis 略 过 指定 数量 的 记录 ,还 有 限制 返回 结果 的 数量 。 
RowBounds 类 有 一 个 构造 方法 来 接收 offset 和 limit, 和 否则 是 不 可 改变 的 。 


int offset = 100; 
int limit = 25; 
RowBounds rowBounds = new RowBounds(offset, limit); 


不 同 的 驱动 会 实现 这 方面 的 不 同 级 别 的 效率 。 对 于 最 佳 的 表现 ,使 用 结果 集 类 型 的 
SCROLL_SENSITIVE 或 SCROLL_INSENSITIVE( 3 4) 787%: 7 Æ 
FORWARD_ONLY) ° 


ResultHandler 参数 允许 你 按 你 喜欢 的 方式 处 理 每 一 行 。 你 可 以 将 它 添加 到 List P, 
创 建 Map, 或 抛 出 每 个 结果 而 不 是 只 保留 总 计 。 Set 你 可 以 使 用 ResultHandler 做 
很 多 漂亮 的 事 , 那 就 是 MyBatis 内 部 创建 结果 集 列 表 。 


它 的 接口 很 简单 。 
package org.apache.ibatis.session; 


public interface ResultHandler<T> { 
void handleResult(ResultContext<? extends T> context); 


} 


ResultContext 参数 给 你 访问 结果 对 象 本 身 的 方法 , 大 量 结果 对 象 被 创建 , 你 可 以 使 
用 布 尔 返回 值 的 MyBatis 加 载 更 多 的 结果 。 


Batch update statement Flush Method 


There is method for flushing(executing) batch update statements that stored in a 
JDBC driver class at any timing. This method can be used when you use the 
ExecutorType.BATCH as ExecutorType . 


List<BatchResult> flushStatements() 


事务 控制 方法 


A 


务 管 理 器 ,这 就 没有 任何 效果 了 。 然 而 ,如 果 你 正在 使 用 JDBC 事务 管理 员 , 由 
Connection 实 例 来 控制 ,那么 这 四 个 方法 就 会 派 上 用 场 : 


| 事务 范围 有 四 个 方法 。 当然 , 如 果 你 已 经 选择 了 自动 提交 或 你 正在 使 用 外 部 事 


void commit() 

void commit(boolean force) 
void rollback() 

void rollback(boolean force) 


默认 情况 下 MyBatis 不 会 自动 提交 事务 , 除非 它 侦 测 到 有 插入 , 更 新 或 删除 操作 改变 
了 数据 库 。 如 果 你 已 经 做 出 了 一 些 改变 而 没有 使 用 这 些 方法 ,那么 你 可 以 传递 true 
到 commit 和 rollback 方法 来 保证 它 会 被 提交 (注意 ,你 不 能 在 自动 提交 模式 下 强制 
session, 或 者 使 用 了 外 部 事务 管理 器 时 )。 很 多 时 候 你 不 用 调用 rollback(), 因 为 如 果 
你 没有 调用 commit 时 MyBatis 会 蔡 你 完成 。 然 而 ,如 果 你 需要 更 多 对 多 提交 和 回 滚 
都 可 能 的 session 的 细 粒 度 控 制 ,你 可 以 使 用 回 滚 选 择 来 使 它 成 为 可 能 。 


NOTE MyBatis-Spring and MyBatis-Guice provide declarative transaction 
handling. So if you are using MyBatis with Spring or Guice please refer to their 
specific manuals. 


清理 Session 级 的 缓存 


void clearCache() 


SqlSession 实例 有 一 个 本 地 缓存 在 执行 update,commit,rollback 和 close 时 被 清 
理 。 要 明确 地 关闭 它 ( 获 取 打 算 做 更 多 的 工作 ) ,你 可 以 调用 clearCache()。 


确保 SqlSession 被 关闭 


void close() 


你 必须 保证 的 最 重要 的 事情 是 你 要 关闭 所 打开 的 任何 session。 保 证 做 到 这 点 的 最 
佳 方 式 是 下 面 的 工作 模式 : 


SqlSession session = sqlSessionFactory.openSession(); 
try { 
// following 3 lines pseudocod for "doing some work" 
session.insert(...); 
session.update(...); 
session.delete(...); 
session.commit(); 
} finally { 
session.close(); 
} 


还 有 ， 如 果 你 正在 使 用 jdk 1.7 以 上 的 版 本 还 有 MyBatis 3.2 以 上 的 版 本 ， 你 可 以 使 用 
try-with-resourcesé 4 : 


try (SqlSession session = sqlSessionFactory.openSession()) { 
// following 3 lines pseudocode for "doing some work" 
session.insert(...); 
session.update(...); 
session.delete(...); 
session.commit(); 


+ 4a 


注意 就 像 SqlSessionFactory, 你 可 以 通过 调用 getConfiguration() 方 法 获得 
SqlSession 使 用 的 Configuration 实例 


Configuration getConfiguration() 


使 用 映射 器 


<T> T getMapper (Class<T> type) 


上 述 的 各 个 insert,update,delete 和 select 方法 都 很 强大 ,但 也 有 些 繁琐 ,没有 类 型 安 
全 ,对 于 你 的 IDE 也 没有 帮助 ,还 有 可 能 的 单元 测试 。 在 上 面 的 入 门 章节 中 我 们 已 经 
看 到 了 一 个 使 用 映射 器 的 示例 。 


因此 , 一 个 更 通用 的 方式 来 执行 映射 语 多 是 使 用 映射 器 类 。 一 个 映射 器 类 就 是 一 个 
简单 的 接口 ,其 中 的 方法 定义 匹配 于 SqlSession 方法 。 下 面 的 示例 展示 了 一 些 方法 
签名 和 它们 是 如 何 映射 到 SqlSession 的 。 


public interface AuthorMapper { 
// (Author) selectOne("selectAuthor",5); 
Author selectAuthor(int id); 
// (List<Author>) selectList(“selectAuthors” ) 
List<Author> selectAuthors(); 
// (Map<Integer,Author>) selectMap("SelectAuthors", "id") 
@MapKey ("id") 
Map<Integer, Author> selectAuthors(); 
// insert("insertAuthor", author) 
int insertAuthor(Author author); 
// updateAuthor("updateAuthor", author) 
int updateAuthor(Author author); 
// delete("deleteAuthor",5) 
int deleteAuthor(int id); 


总 之 , 每 个 映射 器 方法 签名 应 该 匹配 相关 联 的 SqlSession 方法 , 而 没有 字符 串 参 数 
ID 。 相反 ,方法 名 必须 匹配 映射 语句 的 ID。 


此 外 ,返回 类 型 必须 匹配 期 望 的 结果 类 型 。 所 有 常用 的 类 型 都 是 支持 的 ,包括 :原生 类 
型 ,Map,POJO 和 JavaBean ° 


映射 器 接口 不 需要 去 实现 任何 接口 或 扩展 任何 类 。 只 要 方法 前 面 可 以 被 用 来 唯一 标 
识 对 应 的 映射 语句 就 可 以 了 。 


映射 器 接口 可 以 扩展 其 他 接口 。 当 使 用 XML 来 构建 映射 器 接口 时 要 保证 在 合适 的 
命名 空间 中 有 语句 。 而且, 唯一 的 限制 就 是 你 不 能 在 两 个 继承 关系 的 接口 中 有 相同 
的 方法 签名 (这 也 是 不 好 的 想法 )。 


你 可 以 传递 多 个 参数 给 一 个 映射 器 方法 。 如 果 你 这 样 做 了 , 默认 情况 下 它们 将 会 以 
它们 在 参数 列表 中 的 位 置 来 命名 ,比如 :#{param1}),#{param2} 等 。 如 果 你 想 改 变 参数 
的 名 称 (只 在 多 参数 情况 下 ) ,那么 你 可 以 在 参数 上 使 用 @Param('paramName”) 注 
解 。 


你 也 可 以 给 方法 传递 一 个 RowBounds 实例 来 限制 查询 结果 。 
映射 器 注解 


为 最 初 设 计时 ,MyBatis 是 一 个 XML 驱动 的 框架 。 配 置信 息 是 基于 XML 的 ,而 且 
映射 语句 也 是 定义 在 XML 中 的 。 而 到 了 MyBatis 3, 有 新 的 可 用 的 选择 了 。MyBatis 
3 构建 在 基于 全 面 而 且 强 大 的 Java 配置 API 之 上 。 这 个 配置 API 是 基于 XML 的 
MyBatis 配置 的 基础 ,也 是 新 的 基于 注解 配置 的 基础 。 注 解 提 供 了 一 种 简单 的 方式 来 
实现 简单 映射 语句 ,而 不 会 引入 大 量 的 开销 。 

注意 不 幸 的 是 ,Java 注解 限制 了 它们 的 表现 和 灵活 。 尽 管 很 多 时 间 都 花 调查 ,设计 和 
实验 上 ,最 强大 的 MyBatis 映射 不 能 用 注解 来 构建 , 那 并 不 可 笑 。C# 属 性 (做 示例 ) 就 
没有 这 些 限制 ,因此 MyBatis.NET 将 会 比 XML 有 更 丰富 的 选择 。 也 就 是 说 ,基于 
Java 注解 的 配置 离 不 开 它 的 特性 。 


注解 有 下 面 这 些 : 
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映射 申明 样 例 
这 个 例子 展示 了 如 何 使 用 @SelectKey 注解 来 在 插入 前 读 取 数据 库 序列 的 值 : 


@Insert("insert into table3 (id, name) values(#{nameId}, #{name} 
)") 

@SelectKey(statement="call next value for TestSequence", keyProp 
erty="nameId", before=**true**, resultType=**int.class**) 
**int** insertTable3(Name name); 


这 个 例子 展示 了 如 何 使 用 @SelectKey 注解 来 在 插入 后 读 取 数据 库 识别 列 的 值 : 


@Insert("insert into table2 (name) values(#{name})") 
@SelectKey(statement="call identity()", keyProperty="nameId", be 
fore=**false**, resultType=**int.class**) 

**int** insertTable2(Name name); 


This example shows using the @Flush annotation to call the 
SqlSession#flushStatements() : 


@Flush 
List<BatchResult> flush(); 


These examples show how to name a ResultMap by specifying id attribute of 
@Results annotation. 


@Results(id = "userResult", value = { 
@Result(property = "id", column = "uid", id = **true**), 
@Result(property = "firstName", column = "first_name"), 
@Result(property = "lastName", column = "last_name") 

}) 


@Select("select * from users where id = #{id}") 
User getUserById(Integer id); 


@Results(id = "companyResults" ) 


@ConstructorArgs({ 
@Arg(property = "id", column = "cid", id = **true**), 
@Arg(property = "name", column = "name") 

}) 


@Select("select * from company where id = #{id}") 
Company getCompanyById(Integer id); 


SQL 语 名 构建 器 类 


问题 


Java 程 序 员 面 对 的 最 痛苦 的 事情 之 一 就 是 在 Java 代 码 中 获 入 SQL 语 旬 。 这 么 来 做 通 
常 是 由 于 SQL 语 句 需 要 动态 来 生成 -否则 可 以 将 它们 放 到 外 部 文件 或 者 存储 过 程 中 。 
正如 你 已 经 看 到 的 那样 ，MyBatis 在 它 的 XML 映射 特性 中 有 一 个 强大 的 动态 SQL 生 
成 方案 。 但 有 时 在 Java 代 码 内 部 创建 SQL 语句 也 是 必要 的 。 此 时 ，MyBatis 有 另外 
oe PET VAR BAR > ARS RAL ho 31 SAAT AC fe RA KARR 

多 余 的 过 号 或 AND 连接 词 之 前 。 事 实 上 ， 在 Java 代 码 中 来 动态 生成 SQL 代码 就 是 
HEA o te : 


String sql = "SELECT P.ID, P.USERNAME, P.PASSWORD, P.FULL_NAME, 


"P, LAST_NAME, P.CREATED_ON, P.UPDATED_ON " + 
"EROM PERSON P, ACCOUNT A " + 

"INNER JOIN DEPARTMENT D on D.ID = P.DEPARTMENT_ID " + 
"INNER JOIN COMPANY C on D.COMPANY_ID = C.ID " + 
"WHERE (P.ID = A.ID AND P.FIRST_NAME like ?) " + 

"OR (P.LAST_NAME like ?) " + 

"GROUP BY P.ID " + 

"HAVING (P.LAST_NAME like ?) " + 

"OR (P.FIRST_NAME like ?) " + 

"ORDER BY P.ID, P.FULL_NAME"; 


The Solution 


MyBatis 3 提供 了 方便 的 工具 类 来 帮助 解决 该 问题 。 使 用 SQL 类 ， 简 单 地 创建 一 个 实 
例 来 调用 方法 生成 SQL 语句 。 上 面 示例 中 的 问题 就 像 重 写 SQL 类 那样 : 


private String selectPersonSql() { 

return new SQL() {{ 
SELECT("P.ID, P.USERNAME, P.PASSWORD, P.FULL_NAME"); 
SELECT("P.LAST_NAME, P.CREATED_ON, P.UPDATED_ON"); 
FROM("PERSON P"); 
FROM("ACCOUNT A"); 
INNER_JOIN("DEPARTMENT D on D.ID = P.DEPARTMENT_ID"); 
INNER_JOIN( "COMPANY C on D.COMPANY_ID = C.ID"); 
WHERE("P.ID = A.ID"); 
WHERE("P.FIRST_NAME like ?"); 
OR(); 
WHERE("P.LAST_NAME like ?"); 
GROUP_BY("P.ID"); 
HAVING("P.LAST_NAME like ?"); 
OR(); 
HAVING("P.FIRST_NAME like ?"); 
ORDER_BY("P.ID"); 
ORDER_BY("P.FULL_NAME"); 

}}.toString(); 


} 


该 例 中 有 什么 特殊 之 处 ? 当 你 仔细 看 时 ， 那 不 用 担心 偶然 间 重 复出 现 的 "AND" 关 键 
字 ， 或 者 在 "WHERE'" 和 "AND" 之 间 的 选择 ， 抑 或 什么 都 不 选 。 该 SQL 类 非常 注 
意 "WHERE" 应 该 出 现在 何 处 ， 哪 里 又 应 该 使 用 "AND"， 还 有 所 有 的 字符 串 链 接 。 


// Anonymous inner class 
public String deletePersonSql() { 
return new SQL() {{ 
DELETE_FROM("PERSON") ; 
WHERE("ID = ${id}"); 
}}.toString(); 
} 


// Builder / Fluent style 
public String insertPersonSql() { 
String sql = new SQL() 
. INSERT_INTO( "PERSON" ) 
.VALUES( "ID, FIRST_NAME", "${id}, ${firstName}") 
.VALUES("LAST_NAME", "${lastName}") 
.toString(); 
return sql; 


} 


// With conditionals (note the final parameters, required for th 
e anonymous inner class to access them) 


public String selectPersonLike(final String id, final String fir 
stName, final String lastName) { 
return new SQL() {{ 

SELECT("P.ID, P.USERNAME, P.PASSWORD, P.FIRST_NAME, P.LAST_N 
AME"); 

FROM( "PERSON P"); 

if (id != null) { 

WHERE ("P.ID like ${id}"); 


if (firstName != null) { 
WHERE ( "P. FIRST_NAME like ${firstName}"); 


} 
if (lastName != null) { 
WHERE("P.LAST_NAME like ${lastName}"); 


} 
ORDER_BY("P.LAST_NAME"); 
}}.toString(); 


public String deletePersonSql() { 
return new SQL() {{ 
DELETE_FROM( "PERSON" ) ， 
WHERE( "ID = ${id}"); 
}}.toString(); 
} 


public String insertPersonSql() { 
return new SQL() {{ 
INSERT_INTO("PERSON"); 
VALUES( "ID, FIRST_NAME", "${id}, ${firstName}"); 
VALUES("LAST_NAME", "${lastName}"); 
}}.toString(); 


public String updatePersonSql() { 
return new SQL() {{ 
UPDATE("PERSON") ; 
SET("FIRST_NAME = ${firstName}"); 
WHERE("ID = ${id}"); 
}}.toString(); 


方法 描述 


开始 或 插入 到 SELECT Feo 可 以 被 多 次 
调用 ， 参 数 也 会 添加 到 SELECT FA ° A 
数 通常 使 用 过 号 分 隔 的 列 名 和 别名 列表 ， 但 
也 可 以 是 数据 库 驱 动 程序 接受 的 任意 类 型 。 


开始 或 插入 到 SELECT 子 多 ， 也 可 以 播 入 
DISTINCT «42°F 2] 47 0 41978 47 o 


SELECT(String) 


SELECT_DISTINCT(String) 


FROM(String) 


JOIN(String) 
INNER_JOIN(String) 
LEFT_OUTER_JOIN(String) 
RIGHT_OUTER_JOIN(String) 


WHERE (String) 


OR() 


AND( ) 


GROUP_BY(String) 


HAVING(String) 


ORDER_BY (String) 


DELETE_FROM(String) 


INSERT_INTO(String) 
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可 以 被 多 次 调用 ， 参 数 也 会 添加 到 

SELECT $4) ° 参数 通常 使 用 去 号 分 隔 的 
列 名 和 别名 列表 ， 但 也 可 以 是 数据 库 驱 动 程 
序 接受 的 任意 类 型 。 


开始 或 插入 到 FROM FA o 可 以 被 多 次 调 
用 ， 参 数 也 会 添加 到 FROM FA o 参数 通 
常 是 表 名 或 别名 ， 也 可 以 是 数据 库 驱 动 程序 
接受 的 任意 类 型 。 


基于 调用 的 方法 ， 添 加 新 的 合适 类 型 的 
JOIN Fa e 参数 可 以 包含 由 列 命 和 join on 
条 件 组 合成 标准 的 join 。 


插入 新 的 WHERE 子 名 条件， 由 AND 链 
接 。 可 以 多 次 被 调用 ， 每 次 都 由 AND 来 链 
接 新 条 件 。 使 用 OR() 来 分 隔 OR © 


使 用 OR 来 分 隔 当 前 的 WHERE 7-4) AFF o 
可 以 被 多 次 调用 ， 但 在 一 行 中 多 次 调用 或 生 
成 不 稳定 的 SQL 。 


使 用 AND 来 分 隔 当 前 的 WHERE 子 句 条 
件 。 可 以 被 多 次 调用 ， 但 在 一 行 中 多 次 调用 
或 生成 不 稳定 的 SQL 。 因 为 WHERE 和 
HAVING 二 者 都 会 自动 链接 AND , 这 是 非 
常 军 见 的 方法 ， 只 是 为 了 完整 性 才 被 使 用 。 


插入 新 的 GROUP BY FJA’ hA 
接 。 可 以 被 多 次 调用 ， 每 次 都 由 各 号 连接 新 
的 条 件 。 


插入 新 的 HAVING 子 名 条件。 由 AND 连 
接 。 可 以 被 多 次 调用 ， 每 次 都 由 AND 来 连 
接 新 的 条 件 。 使 用 OR() RAM OR. 
插入 新 的 ORDER BY FJAR’ Wis Fie 
接 。 可 以 多 次 被 调用 ， 每 次 由 去 号 连接 新 的 
条 件 。 

开始 一 个 delete 语 名 并 指定 需要 从 哪个 表 删 
除 的 表 名 。 通 常 它 后 面 都 会 跟着 VWVHERE 语 
4] | 

开始 一 个 insert 语 句 并 指定 需要 插入 数据 的 表 
名 。 后 面 都 会 跟着 一 个 或 者 多 个 
VALUES() ° 


针对 Update 语句 ， 插 入 到 "set" 列 表 中 
开始 一 个 update 语 名 并 指定 需要 更 新 的 表 


UPDATE(String) 明 。 后 面 都 会 跟着 一 个 或 者 多 个 SET()， 通 
常 也 会 有 一 个 WHERE() ° 


插入 到 insert 语 名 中 。 第 一 个 参数 是 要 插入 的 
PSN ES I GoM SENG) 列 名 ， 第 二 个 参数 则 是 该 列 的 值 。 
SqlBuilder 和 SelectBuilder (已 经 废弃 ) 
在 3.2 版 本 之 前 ， 我 们 使 用 了 一 点 不 同 的 做 法 ， 通 过 实现 ThreadLocal 交 量 来 掩盖 一 
些 导 致 Java DSL 麻 烦 的 语言 限制 。 但 这 种 方式 已 经 废弃 了 ， 现 代 的 框架 都 欢迎 人 们 
使 用 构建 器 类 型 和 匿名 内 部 类 的 想法 。 因 此 ，SelectBuilder 和 SqlBuilder 类 都 被 废 
ÄT ° 


下 面 的 方法 仅仅 适用 于 废弃 的 SqlBuilder 和 SelectBuilder 类 。 


方法 描述 
BEGIN() 这 些 方法 清空 SelectBuilder 类 的 ThreadLocal 状 态 ， 并 且 准 备 一 个 
j 新 的 构建 语句 。 开 始 新 的 语句 时 ， BEGIN() 读 取得 最 好 。 由 于 
RESET() ”一 些 原因 (在 茶 些 条 件 下 ， 也 许 是 逻辑 需要 一 个 完全 不 同 的 语 
67) ， 在 执行 中 清理 语句 RESET() 读 取得 最 好 。 
返回 生成 的 SQL() 并 重 置 SelectBuilder 状态 (好 像 
SQL() BEGIN() 或 RESET() 被 调用 了 ). 因此 ， 该 方法 只 能 被 调用 一 


ad 


SelectBuilder 和 SqlBuilder 类 并 不 神奇 ， 但 是 知道 它们 如 何 工作 也 是 很 重要 的 。 
SelectBuilder 使 用 SqlBuilder 使 用 了 静态 导入 和 ThreadLocal 变 量 的 组 合 来 开 尼 整 
洁 语法 ， 可 以 很 容易 地 和 条 件 交 错 。 使 用 它们 ， 静 态 导 入 类 的 方法 即 可 ， 就 像 这 样 
(一 个 或 其 它 ， 并 非 两 者 ): 


import static org.apache.ibatis.jdbc.SelectBuilder.*; 


import static org.apache.ibatis.jdbc.SqlBuilder.*; 
这 就 允许 像 下 面 这 样 来 创建 方法 : 


/* DEPRECATED */ 
public String selectBlogsSql() { 
BEGIN(); // Clears ThreadLocal variable 
SELEC (Gy; 
FROM("BLOG"); 
return SQL(); 
} 


/* DEPRECATED */ 
private String selectPersonSql() { 
BEGIN(); // Clears ThreadLocal variable 
SELECT("P.ID, P.USERNAME, P.PASSWORD, P.FULL_NAME"); 
SELECT("P.LAST_NAME, P.CREATED_ON, P.UPDATED_ON"); 
FROM( "PERSON P"); 
FROM( "ACCOUNT A"); 
INNER_JOIN( "DEPARTMENT D on D.ID = P.DEPARTMENT_ID"); 
INNER_JOIN( "COMPANY C on D.COMPANY_ID = C.ID"); 
WHERE("P.ID = A.ID"); 
WHERE ( "P. FIRST_NAME like ?"); 
OR(); 
WHERE("P.LAST_NAME like ?"); 
GROUP_BY("P.ID"); 
HAVING("P.LAST_NAME like ?"); 
OR(); 
HAVING("P.FIRST_NAME like ?"); 
ORDER_BY("P.ID"); 
ORDER_BY("P.FULL_NAME"); 
return SQL(); 


Logging 
Mybatis 内 置 的 日 志 工厂 提供 日 志 功 能 ， 具 体 的 日 志 实现 有 以 下 几 种 工具 : 


SLF4J 

Apache Commons Logging 
Log4j 2 

Log4j 

JDK logging 


具体 选择 哪个 日 志 实 现 工 具 由 MyBatis 的 内 置 日 志 工厂 确定 。 它 会 使 用 最 先 找到 的 
( 按 上 文 列 举 的 顺序 查找 ) 。 如 果 一 个 都 未 找到 ， 日 志 功 能 就 会 被 禁用 。 


不 少 应 用 服务 器 的 classpath 中 已 经 包含 Commons Logging， 如 Tomcat 和 
WebShpere ， 所 以 MyBatis 会 把 它 作 为 具体 的 日 志 实 现 。 记 住 这 点 非常 重要 。 这 将 
意味 着 ， 在 诸如 WebSphere 的 环境 中 一 一 WebSphere 提 供 了 Commons Logging 的 
私有 实现 ， 你 的 Log4J 配 置 将 被 忽略 。 这 种 做 法 不 免 让 人 悲 催 ，MyBatis 怎 么 能 忽 
略 你 的 配置 呢 ? 事实 上 ， 因 Commons Logging 已 经 存 在 了 ， 按 照 优先 级 顺序 ， 
Log4J 自 然 就 被 忽略 了 | 不过， 如果 你 的 应 用 部 署 在 一 个 包含 Commons Logging 的 
环境 ， 而 你 又 想 用 其 他 的 日 志 框 架 ， 你 可 以 根据 需要 调用 如 下 的 某 一 方法 : 





org.apache.ibatis.logging.LogFactory.useS1f4jLogging(); 
org.apache.ibatis.logging.LogFactory.useLog4JLogging(); 
org.apache.ibatis.logging.LogFactory.useJdkLogging(); 
org.apache.ibatis.logging.LogFactory.useCommonsLogging(); 
org.apache.ibatis.logging.LogFactory.useStdOutLogging(); 


如 果 的 确 需要 调用 以 上 的 某 个 方法 ， 请 在 其 他 所 有 MyBatis 方 法 之 前 调用 它 。 另 

外 ， 只 有 在 相应 日 志 实 现 中 存在 的 前 提 下 ， 调 用 对 应 的 方法 才 是 有 意义 的 ， 否 则 
MyBatis 一 概 和 忽略 。 如 你 环境 中 并 不 存在 Log4J， 你 却 调用 了 相应 的 方法 ，MyBatis 
就 会 忽略 这 一 调用 ， 代 之 默认 的 查找 顺序 查找 日 志 实 现 。 


关于 SLF4J、Apache Commons Logging、Apache Log4J 和 JDK Logging 的 API 介 
绍 已 经 超出 本 文档 的 范围 。 不过， 下 面 的 例子 可 以 作为 一 个 快速 入 门 。 关 于 这 些 日 
志 框 架 的 更 多 信息 ， 可 以 参考 以 下 链接 : 


e Apache Commons Logging 
e Apache Log4j 
e JDK Logging API 


Logging Configuration 
MyBatis 可 以 对 包 、 类 、 命 名 空间 和 全 限定 的 语句 记录 日 志 。 
具体 怎么 做 ， 视 使 用 的 日 志 框 架 而 定 ， 这 里 以 Log4J 为 例 。 配 置 日 志 功能 非常 简 


单 : 添加 几 个 配置 文件 ， 如 log4j.properties, 再 添加 个 jar 包 ， 如 log4j.jar。 下 面 是 具 
体 的 例子 ， 共 两 个 步骤 : 


步骤 1 : 添加 Log4J 的 jar 包 


因为 采用 Log4J， 要 确保 在 应 用 中 对 应 的 jar 包 是 可 用 的 。 要 满足 这 一 点 ， 只 要 将 jar 
包 添 加 到 应 用 的 classpath 中 即 可 。 Log4J 的 jar 包 可 以 从 上 面 的 链接 中 下 载 。 


具体 而 言 ， 对 于 web 或 企业 应 用 ， 需 要 将 log4j.jar 添加 到 WEB-INF/lib 4 
Ri 对 于 独立 应 用 ， 可 以 将 它 添加 到 jvm 的 -classpath 启动 参数 中 。 


步骤 2 : 配置 Log4J 


配置 Log4J 比 较 简 单 ， 比 如 需要 记录 这 个 mapper 接 口 的 日 志 


package org.mybatis.example; 

public interface BlogMapper { 
@Select("SELECT * FROM blog WHERE id = #{id}") 
Blog selectBlog(int id); 


} 


只 要 在 应 用 的 classpath 中 创建 一 个 名 称 为 log4j.properties 的 文件 ， 文 件 的 具 
体内 容 如 下 


# Global logging configuration 

log4j.rootLogger=ERROR, stdout 

# MyBatis logging configuration.. 
log4j.logger.org.mybatis.example. BlogMapper= TRACE 

# Console output. 

10g4j .appender .stdout=org. apache . 10g4j .ConsoleAppender 

log4j .appender.stdout.layout=org.apache.1log4j .PatternLayout 
log4j .appender.stdout.layout.ConversionPattern=%5p [%t] - %m%n 


添加 以 上 配置 后 ，Log4J 就 会 把 org.mybatis .example.BlogMapper 的 详细 执行 
日 志 记 录 下 来 ， 对 于 应 用 中 的 其 它 类 则 仅仅 记录 错误 信息 。 


也 可 以 将 日 志 从 整个 mapper 接 口 级 别 调整 到 到 语 TOR 从 而 实现 更 细 粒 度 的 控 
制 。 pee see selectBlog 语句 的 日 志 


log4j .logger.org.mybatis.example.BlogMapper .selectBlog=TRACE 


与 此 相对 ， 可 以 对 一 组 mapper 接 口 记录 日 志 ， 只 要 对 mapper 接 口 所 在 的 包 开局 日 
志 功 能 即 可 : 


log4j .logger.org.mybatis.example=TRACE 


某 些 查询 可 能 会 返回 大 量 的 数据 ， 只 想 记录 其 执行 的 SQL 语句 该 怎么 办 ?为 此 ， 
Mybatis 中 SQL 语 句 的 日 志 级 别 被 设 为 DEBUG (JDK Logging 中 为 FINE) ， 结 果 日 
志 的 级 别 为 TRACE (JDK Logging 中 为 FINER)。 所 以 ， 只 要 将 日 志 级 别 调整 为 
DEBUG 即 可 达到 目的 : 


log4j .logger .org.mybatis.example=DEBUG 


要 记录 日 志 的 是 类 似 下 面 的 mapper 文 件 而 不 是 mapper 接 口 又 该 怎么 呢 ? 


<?xml version="1.0" encoding="UTF-8" ?> 
<!DOCTYPE mapper 
PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" 
"http://mybatis.org/dtd/mybatis-3-mapper.dtd"> 
<mapper namespace="org.mybatis.example.BlogMapper"> 
<select id="selectBlog" resultType="Blog"> 
select * from Blog where id = #{id} 
</select> 
</mapper> 


对 这 个 文件 记录 上 日志， 只 要 对 命名 空间 增加 日 志 记 录 功 能 即 可 : 
log4j .logger.org.mybatis.example.BlogMapper=TRACE 
进一步 ， 要 记录 具体 语句 的 日 志 可 以 这 样 做 : 


log4j .logger.org.mybatis.example.BlogMapper .selectBlog=TRACE 


看 到 了 吧 ， 两 种 配置 没 差别 ! 


配置 文件 log4j.properties 的 余下 内 容 是 针对 日 志 格式 的 ， 这 一 内 容 已 经 超出 
本 文档 范围 。 关 于 Log4J 的 更 多 内 容 ， 可 以 参考 Log4J 的 网 站 。 不 过 ， 可 以 简单 试 
一 下 看 看 ， 不 同 的 配置 会 产生 什么 不 一 样 的 效果 。 


当 
目 文 和 
项 


项 目 总 体 信 息 


本 文档 提供 了 与 本 项 目 相关 信息 的 各 种 文档 和 链接 的 概述 。 这 里 的 所 有 内 容 都 是 根 
据 本 项 目 信 息 生 成 的 ， 自 动 生 成 过 程 依靠 Maven 。 


概述 
文档 描述 
持续 集成 持续 集成 是 以 一 定 的 频率 和 固定 的 基础 进行 代码 构建 和 测试 的 


项 目 依赖 


过 程 ， 这 里 列 出 了 所 有 的 持续 集成 过 程 。 
这 一 文档 列 出 了 项 目的 依赖 并 提供 了 每 个 依赖 的 相关 信息 。 


Dependency This document describes how to to include this project as a 
Information dependency using various dependency management tools. 
Distribution This document provides informations on the distribution 
Management management of this project. 

7 gE oH oer 这 是 本 项 目 中 的 问题 管理 系统 的 链接 。 用 户 可 以 在 这 里 进行 问 
问题 跟踪 


项 目 授权 


题 (故障 、 特 性 、 变 更 请 求 ) 的 创建 和 查询 。 


这 是 关于 本 项 目 授权 的 定义 。 


邮件 列表 本 文档 提供 了 本 项 目的 邮件 列表 的 订阅 和 归档 信息 。 

Plugin This document lists the plugins that are defined through 
Management pluginManagement. 

Project This document lists the build plugins and the report plugins 
Plugins used by this project. 


项 目 团队 


本 文档 提供 了 本 项 目 中 成 员 的 信息 .他 们 是 在 本 项 目 中 以 某 种 形 
式 做 出 了 贡献 的 个 人 . 


源 代 码 库 这 是 一 个 在 线 代码 库 , 它 可 以 通过 Web 浏 览 器 进行 查看 . 
项 目 概要 此 文档 列 出 了 该 项 目 其 它 的 相关 信息 


概述 

本 项 目 使 用 Travis CI ° 

访问 

以 下 是 在 本 项 目 中 使 用 的 持续 集成 系统 。 


[https://travis-ci.org/mybatis/mybatis-3/](https://travis-ci.org 
/mybatis/mybatis -3/) 


提醒 方法 


未 定义 任何 的 提醒 方法 ， 请 以 后 再 查看 。 


项 目 依赖 


compile 


以 下 是 这 一 项 目的 编译 依赖 列表 。 编 译 和 运行 本 应 用 需要 这 些 依赖 。 


类 : 备 
Groupld Artifactld 版 本 License 2 
ae ve 
cglib cglib 3:1 jar | ASF 2.0 Yes 
The Apache 
commons-logging r 2 jar See le Yes 
logging License, 
Version 2.0 
The Apache 
; f Software 
log4j log4j 1.2.17 jar License: Yes 
Version 2.0 
The Apache 
, Software 
ognl ognl Sro jar License Yes 
Version 2.0 
The Apache 
. . l l Software 
org.apache.logging.log4j log4j-core 2.3 jar Leene. Yes 
Version 2.0 
MPL 1.1- 
' ) . , 3.20.0- . LGPL 2.1- 
org.javassist javassist GA jar Apache Yes 
License 2.0 
org.slf4j slf4j-api 1.7.12 jar | MIT License Yes 
: slf4j- ; , 
org.slf4j log4j12 1.7.12 jar MIT License Yes 
test 


以 下 是 这 一 项 目的 测试 依赖 列表 。 这 些 依赖 仅仅 在 编译 和 运行 本 应 用 中 的 单元 测试 
时 需要 。 


项 目 总 体 信 息 


Groupld 


commons-dbcp 


javax.transaction 


junit 


org.apache.derby 


org.apache.velocity 


org.hsqldb 


org.mockito 


postgresql 


Artifactid 


commons- 
dbcp 


transaction- 
api 


junit 
derby 


velocity 


hsqldb 


mockito- 
core 


postgresql 


4.12 
TORIR 


1.7 


292 


1.10.19 


9.1-901- 
1.jdbc4 


License 


The Apache Software 
License, Version 2.0 


Eclipse Public 
License 1.0 


Apache 2 


The Apache Software 
License, Version 2.0 


HSQLDB License, a 
BSD open source 
license 


The MIT License 


BSD License 
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Dependency Information 
Apache Maven 


<dependency> 
<groupiId>org.mybatis</groupId> 
<artifactIid>mybatis</artifactId> 
<version>3.4.0-SNAPSHOT</version> 
</dependency> 


Apache Buildr 


‘'org.mybatis:mybatis:jar:3.4.0-SNAPSHOT' 


Apache lvy 


<dependency org="org.mybatis" name="mybatis" rev="3.4.0-SNAPSHOT 
Ws 

<artifact name="mybatis" type="jar" /> 
</dependency> 


Groovy Grape 


@Grapes( 
@Grab(group='org.mybatis', module='mybatis', version='3.4.0-SNAP 
SHOT' ) 


) 


Grails 


compile 'org.mybatis:mybatis:3.4.0-SNAPSHOT' 


Leiningen 


[org.mybatis/mybatis "3.4.0-SNAPSHOT" | 


SBT 


libraryDependencies += "org.mybatis" % "mybatis" % "3.4.0-SNAPSH 
oT" 


Overview 

The following is the distribution management information used by this project. 
Repository - sonatype-nexus-staging 
https://oss.sonatype.org/service/local/staging/deploy/maven2/ 


Snapshot Repository - sonatype-nexus-snapshots 
https://oss.sonatype.org/content/repositories/snapshots/ 
Site - gh-pages 


git:ssh://git@github.com/mybatis/mybatis-3.git?gh-pages# 


概述 

本 项 目 使 用 GitHub Issue Management 管 理 问题 。 

问题 跟踪 

问题 、 故 障 和 新 特性 请 求 请 通过 下 述 的 本 项 目的 问题 跟踪 系统 提交 。 


[https://github.com/mybatis/mybatis-3/issues](https://github.com 
/mybatis/mybatis -3/issues ) 


概述 


一 般 来 说 ， 项 目 中 所 列 的 授权 仅 对 项 目 自身 而 言 ， 不 包括 项 目的 依赖 。 
项 目 授 权 


The Apache Software License, Version 2.0 


Apache License 
Version 2.0, January 2004 
http://www.apache.org/licenses/ 


TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 
1\. Definitions. 


"License" shall mean the terms and conditions for use, rep 
roduction, 

and distribution as defined by Sections 1 through 9 of thi 
s document. 


"Licensor" shall mean the copyright owner or entity author 
ized by 
the copyright owner that is granting the License. 


"Legal Entity" shall mean the union of the acting entity a 
nd all 

other entities that control, are controlled by, or are und 
er common 

control with that entity. For the purposes of this definit 


ion, 

"control" means (i) the power, direct or indirect, to caus 
e the 

direction or management of such entity, whether by contrac 
t or 


otherwise, or (ii) ownership of fifty percent (50%) or mor 
e of the 

outstanding shares, or (iii) beneficial ownership of such 
entity. 


"You" (or "Your") shall mean an individual or Legal Entity 
exercising permissions granted by this License. 


"Source" form shall mean the preferred form for making mod 
ifications, 

including but not limited to software source code, documen 
tation 


source, and configuration files. 


"Object" form shall mean any form resulting from mechanica 


i transformation or translation of a Source form, including 
a not limited to compiled object code, generated documentati 
ae and conversions to other media types. 

"Work" shall mean the work of authorship, whether in Sourc 
e or 


Object form, made available under the License, as indicate 
d bya 

copyright notice that is included in or attached to the wo 
rk 

(an example is provided in the Appendix below). 


"Derivative Works" shall mean any work, whether in Source 
or Object 

form, that is based on (or derived from) the Work and for 
which the 

editorial revisions, annotations, elaborations, or other m 
odifications 

represent, as a whole, an original work of authorship. For 

the purposes 

of this License, Derivative Works shall not include works 
that remain 

separable from, or merely link (or bind by name) to the in 
terfaces of, 

the Work and Derivative Works thereof. 


"Contribution" shall mean any work of authorship, includin 
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the original version of the Work and any modifications or 
additions 

to that Work or Derivative Works thereof, that is intentio 
nally 

submitted to Licensor for inclusion in the Work by the cop 
yright owner 

or by an individual or Legal Entity authorized to submit o 
n behalf of 

the copyright owner. For the purposes of this definition, 
"submitted" 

means any form of electronic, verbal, or written communica 
tion sent 

to the Licensor or its representatives, including but not 
limited to 

communication on electronic mailing lists, source code con 
trol systems, 

and issue tracking systems that are managed by, or on beha 
lf of, the 

Licensor for the purpose of discussing and improving the W 


ork，but 

excluding communication that is conspicuously marked or ot 
herwise 

designated in writing by the copyright owner as "Not a Con 
tribution." 


"Contributor" shall mean Licensor and any individual or Le 
gal Entity 

on behalf of whom a Contribution has been received by Lice 
nsor and 

subsequently incorporated within the Work. 


2\. Grant of Copyright License. Subject to the terms and cond 
itions of 
this License, each Contributor hereby grants to You a perp 


etual, 

worldwide, non-exclusive, no-charge, royalty-free, irrevoc 
able 

copyright license to reproduce, prepare Derivative Works o 
f, 


publicly display, publicly perform, sublicense, and distri 
bute the 
Work and such Derivative Works in Source or Object form. 


3\. Grant of Patent License. Subject to the terms and conditi 
ons of 
this License, each Contributor hereby grants to You a perp 
etual, 
worldwide, non-exclusive, no-charge, royalty-free, irrevoc 
able 
(except as stated in this section) patent license to make, 
have made, 
use, offer to sell, sell, import, and otherwise transfer t 
he Work, 
where such license applies only to those patent claims lic 
ensable 
by such Contributor that are necessarily infringed by thei 
r 
Contribution(s) alone or by combination of their Contribut 
ion(s) 
with the Work to which such Contribution(s) was submitted. 
If You 
institute patent litigation against any entity (including 
a 
cross-claim or counterclaim in a lawsuit) alleging that th 
e Work 
or a Contribution incorporated within the Work constitutes 
direct 
or contributory patent infringement, then any patent licen 
ses 
granted to You under this License for that Work shall term 
inate 
as of the date such litigation is filed. 


A\. Redistribution. You may reproduce and distribute copies o 
f the 
Work or Derivative Works thereof in any medium, with or wi 
thout 
modifications, and in Source or Object form, provided that 
You 
meet the following conditions: 


(a) You must give any other recipients of the Work or 
Derivative Works a copy of this License; and 


(b) You must cause any modified files to carry prominent n 
otices 
stating that You changed the files; and 


(c) You must retain, in the Source form of any Derivative 


Works 
that You distribute, all copyright, patent, trademark, 
and 
attribution notices from the Source form of the Work, 
excluding those notices that do not pertain to any par 
t of 
the Derivative Works; and 
(d) If the Work includes a "NOTICE" text file as part of i 
ts 


distribution, then any Derivative Works that You distr 
ibute must 
include a readable copy of the attribution notices con 


tained 

within such NOTICE file, excluding those notices that 
do not 

pertain to any part of the Derivative Works, in at lea 
st one 

of the following places: within a NOTICE text file dis 
tributed 

as part of the Derivative Works; within the Source for 
m or 

documentation, if provided along with the Derivative W 
orks; or, 

within a display generated by the Derivative Works, if 
and 

wherever such third-party notices normally appear. The 
contents 

of the NOTICE file are for informational purposes only 
and 

do not modify the License. You may add Your own attrib 
ution 

notices within Derivative Works that You distribute, a 
longside 


or as an addendum to the NOTICE text from the Work, pr 
ovided 


that such additional attribution notices cannot be con 
strued 
as modifying the License. 


You may add Your own copyright statement to Your modificat 
ions and 

may provide additional or different license terms and cond 
itions 

for use, reproduction, or distribution of Your modificatio 
ns, or 

for any such Derivative Works as a whole, provided Your us 
e, 

reproduction, and distribution of the Work otherwise compl 
ies with 

the conditions stated in this License. 


5\. Submission of Contributions. Unless You explicitly state 

otherwise, 

any Contribution intentionally submitted for inclusion in 
the Work 

by You to the Licensor shall be under the terms and condit 
ions of 

this License, without any additional terms or conditions. 

Notwithstanding the above, nothing herein shall supersede 
or modify 

the terms of any separate license agreement you may have e 
xecuted 

with Licensor regarding such Contributions. 


6\. Trademarks. This License does not grant permission to use 
the trade 
names, trademarks, service marks, or product names of the 
Licensor, 
except as required for reasonable and customary use in des 
cribing the 
Origin of the Work and reproducing the content of the NOTI 
CE file. 


7\. Disclaimer of Warranty. Unless required by applicable law 
or 
agreed to in writing, Licensor provides the Work (and each 
Contributor provides its Contributions) on an "AS IS" BASI 
S, 
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either expre 
ss or 
implied, including, without limitation, any warranties or 
conditions 
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FO 
RA 
PARTICULAR PURPOSE. You are solely responsible for determi 
ning the 
appropriateness of using or redistributing the Work and as 
sume any 


risks associated with Your exercise of permissions under t 
his License. 


8\. Limitation of Liability. In no event and under no legal t 

heory, 

whether in tort (including negligence), contract, or other 
wise, 

unless required by applicable law (such as deliberate and 
grossly 

negligent acts) or agreed to in writing, shall any Contrib 
utor be 

liable to You for damages, including any direct, indirect, 

special, 

incidental, or consequential damages of any character aris 
ing as a 

result of this License or out of the use or inability to u 
se the 

Work (including but not limited to damages for loss of goo 
dwill, 

work stoppage, computer failure or malfunction, or any and 
all 

other commercial damages or losses), even if such Contribu 
tor 

has been advised of the possibility of such damages. 


9\. Accepting Warranty or Additional Liability. While redistr 
ibuting 
the Work or Derivative Works thereof, You may choose to of 
fer, 
and charge a fee for, acceptance of Support, warranty, ind 
emnity, 
or other liability obligations and/or rights consistent wi 
th this 
License. However, in accepting such obligations, You may a 
ct only 
on Your own behalf and on Your sole responsibility, not on 
behalf 
of any other Contributor, and only if You agree to indemni 
fy, 
defend, and hold each Contributor harmless for any liabili 
ty 
incurred by, or claims asserted against, such Contributor 
by reason 
of your accepting any such warranty or additional liabilit 


y. 
END OF TERMS AND CONDITIONS 
APPENDIX: How to apply the Apache License to your work. 
| To apply the Apache License to your work, attach the follo 
wing 


boilerplate notice, with the fields enclosed by brackets " 


replaced with your own identifying information. (Don't inc 


lude 

the brackets!) The text should be enclosed in the appropr 
iate 

comment syntax for the file format. We also recommend that 
a 


file or class name and description of purpose be included 
on the 

same "printed page" as the copyright notice for easier 

identification within third-party archives. 


Copyright [yyyy] [name of copyright owner] 


Licensed under the Apache License, Version 2.0 (the "License" 
); 

you may not use this file except in compliance with the Licen 
se. 

You may obtain a copy of the License at 


http://www.apache.org/licenses/LICENSE-2.0 


Unless required by applicable law or agreed to in writing, so 
ftware 

distributed under the License is distributed on an "AS IS" BA 
SIS, 

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 
or implied. 

See the License for the specific language governing permissio 
ns and 

limitations under the License. 


The Apache Software License, Version 2.0 


Apache License 
Version 2.0, January 2004 
http://www.apache.org/licenses/ 


TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 
1\. Definitions. 


"License" shall mean the terms and conditions for use, rep 
roduction, 

and distribution as defined by Sections 1 through 9 of thi 
s document. 


"Licensor" shall mean the copyright owner or entity author 
ized by 
the copyright owner that is granting the License. 


"Legal Entity" shall mean the union of the acting entity a 
nd all 

other entities that control, are controlled by, or are und 
er common 

control with that entity. For the purposes of this definit 


ion, 

"control" means (i) the power, direct or indirect, to caus 
e the 

direction or management of such entity, whether by contrac 
t or 


otherwise, or (ii) ownership of fifty percent (50%) or mor 
e of the 

outstanding shares, or (iii) beneficial ownership of such 
entity. 


"You" (or "Your") shall mean an individual or Legal Entity 
exercising permissions granted by this License. 


"Source" form shall mean the preferred form for making mod 
ifications, 

including but not limited to software source code, documen 
tation 

source, and configuration files. 


"Object" form shall mean any form resulting from mechanica 


i transformation or translation of a Source form, including 
ii not limited to compiled object code, generated documentati 
e and conversions to other media types. 

"Work" shall mean the work of authorship, whether in Sourc 
e or 


Object form, made available under the License, as indicate 
d by a 

copyright notice that is included in or attached to the wo 
rk 

(an example is provided in the Appendix below). 


"Derivative Works" shall mean any work, whether in Source 
or Object 

form, that is based on (or derived from) the work and for 
which the 

editorial revisions, annotations, elaborations, or other m 
odifications 

represent, as a whole, an original work of authorship. For 

the purposes 

of this License, Derivative Works shall not include works 
that remain 

separable from, or merely link (or bind by name) to the in 
terfaces of, 

the Work and Derivative Works thereof. 


"Contribution" shall mean any work of authorship, includin 
9 

the original version of the Work and any modifications or 
additions 

to that Work or Derivative Works thereof, that is intentio 
nally 

submitted to Licensor for inclusion in the Work by the cop 
yright owner 

or by an individual or Legal Entity authorized to submit o 
n behalf of 

the copyright owner. For the purposes of this definition, 
"submitted" 

means any form of electronic, verbal, or written communica 
tion sent 

to the Licensor or its representatives, including but not 
limited to 

communication on electronic mailing lists, source code con 
trol systems, 

and issue tracking systems that are managed by, or on beha 
lf of, the 

Licensor for the purpose of discussing and improving the W 
ork，but 

excluding communication that is conspicuously marked or ot 
herwise 

designated in writing by the copyright owner as "Not a Con 
tribution." 


"Contributor" shall mean Licensor and any individual or Le 
gal Entity 

on behalf of whom a Contribution has been received by Lice 
nsor and 

subsequently incorporated within the Work. 


2\. Grant of Copyright License. Subject to the terms and cond 
itions of 
this License, each Contributor hereby grants to You a perp 


etual, 

worldwide, non-exclusive, no-charge, royalty-free, irrevoc 
able 

copyright license to reproduce, prepare Derivative Works o 
f, 


publicly display, publicly perform, sublicense, and distri 
bute the 
Work and such Derivative Works in Source or Object form. 


3\. Grant of Patent License. Subject to the terms and conditi 
ons of 
this License, each Contributor hereby grants to You a perp 
etual, 
worldwide, non-exclusive, no-charge, royalty-free, irrevoc 
able 
(except as stated in this section) patent license to make, 


have made, 

use, offer to sell, sell, import, and otherwise transfer t 
he Work, 

where such license applies only to those patent claims lic 
ensable 

by such Contributor that are necessarily infringed by thei 
$ 

Contribution(s) alone or by combination of their Contribut 
ion(s) 

with the Work to which such Contribution(s) was submitted. 
If You 

institute patent litigation against any entity (including 
a 

cross-claim or counterclaim in a lawsuit) alleging that th 
e Work 

or a Contribution incorporated within the Work constitutes 
direct 

or contributory patent infringement, then any patent licen 
ses 

granted to You under this License for that Work shall term 
inate 

as of the date such litigation is filed. 


4\. Redistribution. You may reproduce and distribute copies o 
f the 
Work or Derivative Works thereof in any medium, with or wi 
thout 
modifications, and in Source or Object form, provided that 
You 
meet the following conditions: 


(a) You must give any other recipients of the Work or 
Derivative Works a copy of this License; and 


(b) You must cause any modified files to carry prominent n 
otices 
stating that You changed the files; and 


(c) You must retain, in the Source form of any Derivative 


Works 
that You distribute, all copyright, patent, trademark, 
and 
attribution notices from the Source form of the Work, 
excluding those notices that do not pertain to any par 
t of 
the Derivative Works; and 
(d) If the Work includes a "NOTICE" text file as part of i 
ts 


distribution, then any Derivative Works that You distr 
ibute must 

include a readable copy of the attribution notices con 
tained 


within such NOTICE file, excluding those notices that 


do not 
pertain to any part of the Derivative Works, in at lea 
st one 
of the following places: within a NOTICE text file dis 
tributed 
as part of the Derivative Works; within the Source for 
m or 
documentation, if provided along with the Derivative W 
orks; or, 
within a display generated by the Derivative Works, if 
and 
wherever such third-party notices normally appear. The 
contents 
of the NOTICE file are for informational purposes only 
and 
do not modify the License. You may add Your own attrib 
ution 
notices within Derivative Works that You distribute, a 
longside 
or as an addendum to the NOTICE text from the Work, pr 
ovided 
that such additional attribution notices cannot be con 
strued 


as modifying the License. 


You may add Your own copyright statement to Your modificat 
ions and 

may provide additional or different license terms and cond 
itions 

for use, reproduction, or distribution of Your modificatio 
ns, or 

for any such Derivative Works as a whole, provided Your us 
e, 

reproduction, and distribution of the Work otherwise compl 
ies with 

the conditions stated in this License. 


5\. Submission of Contributions. Unless You explicitly state 

otherwise, 

any Contribution intentionally submitted for inclusion in 
the Work 

by You to the Licensor shall be under the terms and condit 
ions of 

this License, without any additional terms or conditions. 

Notwithstanding the above, nothing herein shall supersede 
or modify 

the terms of any separate license agreement you may have e 
xecuted 

with Licensor regarding such Contributions. 


6\. Trademarks. This License does not grant permission to use 
the trade 


names, trademarks, service marks, or product names of the 
Licensor, 

except as required for reasonable and customary use in des 
cribing the 

origin of the Work and reproducing the content of the NOTI 
CE file. 


7\. Disclaimer of Warranty. Unless required by applicable law 

or 

agreed to in writing, Licensor provides the Work (and each 

Contributor provides its Contributions) on an "AS IS" BASI 
S, 

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either expre 
ss or 

implied, including, without limitation, any warranties or 
conditions 

of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FO 


RA 

PARTICULAR PURPOSE. You are solely responsible for determi 
ning the 

appropriateness of using or redistributing the Work and as 
sume any 


risks associated with Your exercise of permissions under t 
his License. 


8\. Limitation of Liability. In no event and under no legal t 
heory, 
whether in tort (including negligence), contract, or other 
wise, 
unless required by applicable law (such as deliberate and 
grossly 
negligent acts) or agreed to in writing, shall any Contrib 
utor be 
liable to You for damages, including any direct, indirect, 
special, 
incidental, or consequential damages of any character aris 
ing as a 
result of this License or out of the use or inability to u 
se the 
Work (including but not limited to damages for loss of goo 


dwill, 

work stoppage, computer failure or malfunction, or any and 
all 

other commercial damages or losses), even if such Contribu 
tor 


has been advised of the possibility of such damages. 


9\. Accepting Warranty or Additional Liability. While redistr 
ibuting 
the Work or Derivative Works thereof, You may choose to of 
fer, 
and charge a fee for, acceptance of support, warranty, ind 
emnity, 


or other liability obligations and/or rights consistent wi 
th this 

License. However, in accepting such obligations, You may a 
ct only 

on Your own behalf and on Your sole responsibility, not on 

behalf 

of any other Contributor, and only if You agree to indemni 
fy, 

defend, and hold each Contributor harmless for any liabili 
ty 

incurred by, or claims asserted against, such Contributor 
by reason 

of your accepting any such warranty or additional liabilit 


y. 
END OF TERMS AND CONDITIONS 
APPENDIX: How to apply the Apache License to your work. 

l To apply the Apache License to your work, attach the follo 
jas boilerplate notice, with the fields enclosed by brackets " 
replaced with your own identifying information. (Don't inc 
ao the brackets!) The text should be enclosed in the appropr 
iate 

comment syntax for the file format. We also recommend that 
a 


file or class name and description of purpose be included 
on the 

same "printed page" as the copyright notice for easier 

identification within third-party archives. 


Copyright [yyyy] [name of copyright owner] 


Licensed under the Apache License, Version 2.0 (the "License" 
); 

you may not use this file except in compliance with the Licen 
se. 

You may obtain a copy of the License at 


http://www.apache.org/licenses/LICENSE-2.0 


Unless required by applicable law or agreed to in writing, so 
ftware 

distributed under the License is distributed on an "AS IS" BA 
SIS, 

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 
or implied. 

See the License for the specific language governing permissio 
ns and 

limitations under the License. 
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项 目 邮 件 列表 


这 些 是 本 项 目 建立 的 邮件 列表 。 每 个 列表 都 有 一 个 订阅 、 退 订 和 归档 的 链接 。 


名 称 


mybatis- 
dev 


mybatis- 
USer 


mybatis- 
commits 


订 
阅 


Ii 
阅 


ai 
阅 


7 
阅 


取 
消 
TJ 
阅 
取 
消 
T 
阅 
取 
消 
iT 
阅 
取 
消 
iT 
阅 


发 


归档 


groups.google.com 


groups.google.com 


groups.google.com 


其 他 归档 


mybatis- 
user.963551.n3.nabble.com 
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Project Plugin Management 


Groupld 
com.mycila 
org.apache.maven.plugins 
org.apache.maven.plugins 
org.apache.maven.plugins 


org.apache.maven.plugins 
org.apache.maven.plugins 


org.apache.maven.plugins 
org.apache.maven.plugins 
org.apache.maven.plugins 
org.apache.maven.plugins 
org.apache.maven.plugins 
org.apache.maven.plugins 
org.apache.maven.plugins 
org.apache.maven.plugins 


org.codehaus.mojo 


org.jacoco 


Artifactid 
license-maven-plugin 
maven-antrun-plugin 
maven-assembly-plugin 
maven-clean-plugin 
maven-compiler-plugin 


maven-dependency- 
plugin 


maven-deploy-plugin 
maven-install-plugin 
maven-pdf-plugin 
maven-release-plugin 
maven-resources-plugin 
maven-shade-plugin 
maven-site-plugin 
maven-surefire-plugin 
versions-maven-plugin 


http://jacoco-maven- 
plugin 


Version 
2.11 
1.8 
2:5.5 
2.6.1 
3:3 


210 


2.8.2 
2192 
1.3 
2.0.2 
2.7 
2.4 
3.4 
2.18.1 
2.2 


0.7.5.201505241946 


Oo 
` 


Project Build Plugins 


Groupld 
com.mycila 
org.apache.felix 
org.apache.maven.plugins 
org.apache.maven.plugins 
org.apache.maven.plugins 
org.apache.maven.plugins 
org.apache.maven.plugins 
org.apache.maven.plugins 
org.apache.maven.plugins 
org.apache.maven.plugins 
org.apache.maven.plugins 
org.apache.maven.plugins 
org.apache.maven.plugins 


org.apache.maven.plugins 
org.codehaus.mojo 
org.codehaus.mojo 


org.jacoco 


Artifactld 
license-maven-plugin 
maven-bundle-plugin 
maven-clean-plugin 
maven-compiler-plugin 
maven-deploy-plugin 
maven-enforcer-plugin 
maven-install-plugin 
maven-jar-plugin 
maven-pdf-plugin 
maven-resources-plugin 
maven-scm-plugin 
maven-shade-plugin 
maven-site-plugin 
maven-surefire-plugin 


animal-sniffer-maven- 
plugin 
clirr-maven-plugin 


http://jacoco-maven- 
plugin 


Version 
2.11 
2.5.4 
2.6.1 


2.8.2 


2:9:2 


2.6.1 


0.7.5.201505241946 


` 
da 


Project Report Plugins 


Groupld Artifactld Version 
org.apache.maven.plugins ©maven-changes-plugin 2.11 
org.apache.maven.plugins maven-javadoc-plugin 2.10.3 
org.apache.maven.plugins = maven-jxr-plugin 2.5 
org.apache.maven.plugins maven-pmd-plugin 3.4 


maven-project-info- 28 


org.apache.maven.plugins reports-plugin 


maven-surefire-report- 


org.apache.maven.plugins plugin 2.18.1 
org.codehaus.mojo clirr-maven-plugin 2.6.1 
org.codehaus.mojo findbugs-maven-plugin 9:051 
org.codehaus.mojo jdepend-maven-plugin 2.0 
org.codehaus.mojo taglist-maven-plugin 2.4 
org.codehaus.mojo versions-maven-plugin 2.2 

org.jacoco EE E alee. EMEA 0.7.5.201505241946 


plugin 


Oo 


团队 


一 个 成 功 的 项 目 要 求 许 多 人 扮演 许多 的 角色 。 其 中 一 些 成 员 编写 代码 或 者 文档 ， 同 
时 其 他 成 员 则 通过 测试 、 打 补丁 以 及 提 建 议 等 方式 实现 自己 的 价值 。 


一 个 团队 由 团队 成 员 以 及 贡献 者 组 成 。 团 队 成 员 直 接 访 问 项 目的 源 代码 并 积极 地 参 
与 编码 工作 。 页 献 者 则 通过 向 成 员 提 交 补 本 和 提出 建议 来 完善 项 目 。 一 个 项 目 中 页 
献 者 的 数量 是 不 限 的 。 请 立刻 加 入 到 贡献 行列 中 来 吧 。 户 心 感谢 所 有 对 项 目 做 出 贡 


献 的 人 。 


成 员 


以 下 是 开发 者 的 列表 ， 他 们 有 提交 的 权限 ， 在 项 目 中 以 茶 种 方式 直接 做 出 了 贡献 。 


Image 





cbegin 


brandon.goodin 


mentat6114 


emacarron 


mnesarco 


agustafson 


hpresnall 


harawata 


jeffgbutler 


Id 


姓名 


Clinton 
Begin 


Brandon 
Goodin 


Christian 
Poitras 


Eduardo 
Macarron 


Frank 
Martinez 


Andrew 
Gustafson 


Hunter 
Presnall 


Iwao Ave 


Jeff Butler 


电子 邮件 


clinton.begin@gmail.com 


brandon.goodin@gmail.co 


christian.poitras@ircm.qc.¢ 


eduardo.macarron@gmail. 


mnesarco@gmail.com 


gus4000@gmail.com 


hpresnall@gmail.com 


harawata@gmail.com 


jeffgbutler@gmail.com 


cx rY ~ pepe & 
IM El 总 人 林 信 此 
JN A AITTA IS 


贡献 者 


hazendaz 


nospam@kaigrabfelder.de 


Imeadors 


marcosperanza 


nmaves 


putthibongb 


simonetripodi 


h3adache 


Jeremy 
Landis 


Kai 
Grabfelder 


Larry 
Meadors 


Marco 
Speranza 


Nathan 
Maves 


Putthibong 
Boonbong 


Simone 
Tripodi 


Tim Chen 


jeremylandis@hotmail.con 


nospam@kaigrabfelder.de 


larry. meadors@gmail.com 


marco.speranza79@gmail 


nathan.maves@gmail.com 


putthibongb@gmail.com 


simone.tripodi@gmail.com 


chengt@gmail.com 


以 下 的 其 他 人 通过 建议 ， 补 丁 或 者 文档 对 本 项 目 做 出 了 贡献 。 


Image 


= 
& 


姓名 


Adam Gent 


Andrea Selva 


Antonio Sanchez 


Arkadi Shishlov 


电子 邮件 


adam.gent@evocatus.com 


selva.andre@gmail.com 


juntandolineas@gmail.com 


arkadi.shishlov@gmail.com 
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成 员 


Axel Doerfler 


Chris Dadej 


Denis Vygovskiy 


Franta Mejta 


Jurriaan Pruys 


Keith Wong 


Lasse Voss 


Luke Stevens 


Paul Krause 


Peter Leibiger 


Riccardo Cossu 


Toma? Neuberg 


axel.doerfler@gmail.com 


chris.dadej@gmail.com 


qizant@gmail.com 


mejta@rewor.cz 


jurriaan@pruys.com 


wongkwl@gmail.com 


lasse.voss@motor-talk-gmbh.de 


nosuchluke@gmail.com 


paulkrause88@alum.mit.edu 


kuhnroyal@gmail.com 


riccardo.cossu@gmail.com 


neuberg@m-atelier.cz 


以 下 是 开发 者 的 列表 ， 他 们 有 提交 的 权限 ， 在 项 目 中 以 茶 种 方式 直接 做 出 了 贡献 。 


Image 


Id 


姓名 


电子 邮件 
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Image 





cbegin 


brandon.goodin 


mentat6114 


emacarron 


mnesarco 


agustafson 


hpresnall 


harawata 


jeffgbutler 


hazendaz 


nospam@kaigrabfelder.de 


Imeadors 


marcosperanza 


nmaves 


putthibongb 


姓名 


Clinton 
Begin 


Brandon 
Goodin 


Christian 
Poitras 


Eduardo 
Macarron 


Frank 
Martinez 


Andrew 
Gustafson 


Hunter 
Presnall 


Iwao Ave 


Jeff Butler 


Jeremy 
Landis 


Kai 
Grabfelder 


Larry 
Meadors 


Marco 
Speranza 


Nathan 
Maves 


Putthibong 
Boonbong 


电子 邮件 


clinton.begin@gmail.com 


brandon.goodin@gmail.co 


christian.poitras@ircm.qc.¢ 


eduardo.macarron@gmail. 


mnesarco@gmail.com 


gus4000@gmail.com 


hpresnall@gmail.com 


harawata@gmail.com 


jeffgbutler@gmail.com 


jeremylandis@hotmail.con 


nospam@kaigrabfelder.de 


larry.meadors@gmail.com 


marco.speranza79@gmail 


nathan.maves@gmail.com 


putthibongb@gmail.com 
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广 一 -一 号 一 ~ y II 
a | = 


eee Simone ee ; 
E simonetripodi Tripodi simone.tripodi@gmail.com 
h3adache Tim Chen chengt@gmail.com 
贡献 者 
以 下 的 其 他 人 通过 建议 ， 补 丁 或 者 文档 对 本 项 目 做 出 了 贡献 。 
Image 姓名 电子 邮件 
,SS 
Adam Gent adam.gent@evocatus.com 
Andrea Selva selva.andre@gmail.com 
Antonio Sanchez juntandolineas@gmail.com 
| Arkadi Shishlov arkadi.shishlov@gmail.com 
Axel Doerfler axel.doerfler@gmail.com 





Chris Dadej chris.dadej@gmail.com 
Denis Vygovskiy qizant@gmail.com 
= Franta Mejta mejta@rewor.cz 


E Jurriaan Pruys jurriaan@pruys.com 


2 
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Lasse Voss 


Luke Stevens 


Paul Krause 


Peter Leibiger 


Riccardo Cossu 


Toma? Neuberg 


lasse.voss@motor-talk-gmbh.de 


nosuchluke@gmail.com 


paulkrause88@alum.mit.edu 


kuhnroyal@gmail.com 


riccardo.cossu@gmail.com 


neuberg@m-atelier.cz 
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概述 


This project uses Git to manage its source code. Instructions on Git use can be 
found at http://git-scm.com/documentation. 


Web7z l7] 
以 下 是 在 线 源 代码 库 的 链接 。 


[http://github.com/mybatis/mybatis-3](http://github.com/mybatis/ 
mybatis-3) 


匿名 访问 


The source can be checked out anonymously from Git with this command (See 
http://git-scm.com/docs/git-clone): 


$ git clone ssh://github.com/mybatis/mybatis-3.git 


开发 者 访问 


Only project developers can access the Git tree via this method (See hitp://git- 
scm.com/docs/git-clone). 


$ git clone ssh://git@github.com/mybatis/mybatis-3.git 


通过 防火 墙 访问 


请 参考 使 用 的 源 代码 管理 工具 的 文档 以 获得 更 多 的 通过 防火 墙 进行 访问 的 信息 。 


项 目 概 要 


区 目 信 息 
z 
A t 
名 
称 mybatis 


The MyBatis data mapper framework makes it easier to use a relational 
y database with object-oriented applications. MyBatis couples objects with 
stored procedures or SQL statements using a XML descriptor or 


annotations. Simplicity is the biggest advantage of the MyBatis data 
mapper over object relational mapping tools. 
= http://www.mybatis.org/core/ 


项 目 组 织 


字段 值 
名 称 MyBatis.org 
URL http://www.mybatis.org/ 
构建 信息 
字段 值 
Groupld org.mybatis 
Artifactld mybatis 
版 本 3.4.0-SNAPSHOT 
类 型 jar 
Java Version 1.6 


段 
mybatis 


The MyBatis data mapper framework makes it easier to use a relational 
» database with object-oriented applications. MyBatis couples objects with 


这 stored procedures or SQL statements using a XML descriptor or 
annotations. Simplicity is the biggest advantage of the MyBatis data 
mapper over object relational mapping tools. 

http://www.mybatis.org/core/ 


项 目 组 织 


字段 值 
名 称 MyBatis.org 
URL http://www.mybatis.org/ 
构建 信息 
字段 值 
Groupld org.mybatis 
Artifactld mybatis 
版 本 3.4.0-SNAPSHOT 
类 型 jar 


Java Version 1.6 


生成 报表 


本 文档 提供 了 对 项 目 中 各 种 报表 的 概述 ， 这 些 报表 生成 自 Maven 每 一 个 报表 在 以 
下 简要 介绍 。 


概述 


文档 
JavaDocs 
Source Xref 


Test Source 
Xref 


描述 
JavaDoc API documentation. 
HTML based, cross-reference version of Java source code. 


HTML based, cross-reference version of Java test source 
code. 


JDepend traverses Java class file directories and generates 
design quality metrics for each Java package. JDepend allows 


JDepend you to automatically measure the quality of a design in terms 
of its extensibility, reusability, and maintainability to manage 
package dependencies effectively. 

FindBugs Generates a source code report with the FindBugs Library. 

Surefire 

Report Report on the test results of the project. 

CPD Duplicate code detection. 

PMD Verification of coding rules. 

Tag List Report on various tags found in the code. 

Clirr Report on binary and source API differences between 
releases 

Provides details of the dependencies which have updated 

San versions available. 

Report 

Plugin : : : : 、 

dai Provides details of the plugins used by this project which have 

Ro newer versions available. 

Report 

Property Provides details of properties which control versions of 

Updates dependencies and/or plugins, and indicates any newer 

Report versions which are available. 


概述 


文档 
JavaDocs 
Source Xref 


Test Source 
Xret 


JDepend 


FindBugs 


Surefire 
Report 


CPD 
PMD 
Tag List 


Clirr 


Dependency 
Updates 
Report 


Plugin 
Updates 
Report 


Property 
Updates 
Report 


描述 
JavaDoc API documentation. 
HTML based, cross-reference version of Java source code. 


HTML based, cross-reference version of Java test source 
code. 


JDepend traverses Java class file directories and generates 
design quality metrics for each Java package. JDepend allows 
you to automatically measure the quality of a design in terms 
of its extensibility, reusability, and maintainability to manage 
package dependencies effectively. 


Generates a source code report with the FindBugs Library. 
Report on the test results of the project. 


Duplicate code detection. 
Verification of coding rules. 
Report on various tags found in the code. 


Report on binary and source API differences between 
releases 


Provides details of the dependencies which have updated 
versions available. 


Provides details of the plugins used by this project which have 
newer versions available. 


Provides details of properties which control versions of 
dependencies and/or plugins, and indicates any newer 
versions which are available. 


MyBatis 用 户 手 册 


MyBatis Generator 介 绍 


MyBatis Generator (MBG) 是 一 个 Mybatis 的 代码 生成 器 MyBatis 和 iBATIS. 他 可 以 
生成 Mybatis 各 个 版 本 的 代码 ， 和 iBATIS 2.2.0 版 本 以 后 的 代码 。 他 可 以 内 省 数据 库 
的 表 (或 多 个 表 ) 然后 生成 可 以 用 来 访问 (多 个 ) 表 的 基础 对 象 。 这 样 和 数据 库 表 
进行 交互 时 不 需要 创建 对 象 和 配置 文件 。MBG 的 解决 了 对 数据 库 操作 有 最 大 影响 
的 一 些 简 单 的 CRUD (插入 ， 查 询 ， 更 新 ， 删 除 ) 操作 。 您 仍然 需要 对 联合 查询 和 
存储 过 程 手写 SQL 和 对 象 。 


MyBatis Generator 会 生成 : 
o 匹配 表 结 构 的 Java POJO， 可 能 包括 : 


o 一 个 和 表 主 键 匹 配 的 类 (如 果 存 在 主键 [ 注 : 只 有 联合 主键 会 有 ]) 
o 一 个 包含 了 非 主 键 字段 的 类 (BLOB 字 段 除外 [ 注 :单字 段 做 主键 时 这 里 会 包 
含 ]) 

o 一 个 包含 了 BLOB 字 段 的 类 (如 果 表 包含 了 BLOB 字 段 ) 

o 一 个 允许 动态 查询 、 更 新 和 删除 的 类 [ 注 : 指 的 是 Example 查 询 ] 
这 些 类 之 间 会 有 适当 的 继承 关系 。 请 注意 可 以 配置 生成 器 来 生成 不 同类 型 的 
POJO 的 层次 结构 。 例 如， 如果 您 愿意 您 可 能 会 选择 针对 每 个 表 生 成 一 个 单独 
的 实体 对 象 。 


e MyBatis/iBATIS 兼容 SQL 映射 XML 文件 。MBG 在 配置 中 为 每 个 表 简 单 的 
CRUD 操作 生成 SQL。 生成 的 SQL 语句 包括 : 


insert (插入 ) 

update by primary key (根据 主键 更 新 记录 ) 

update by example (根据 条 件 更 新 记录 ) 

delete by primary key (根据 主键 删除 记录 ) 

delete by example (根据 条 件 删 除 记录 ) 

select by primary key (根据 主键 查询 记录 ) 

select by example (根据 条 件 查询 记录 集 ) 

count by example (根据 条 件 查询 记录 总 数 ) 

根据 表 的 结构 ， 生 成 的 这 些 语句 会 有 不 同 的 变化 (例如 ， 如 果 表 中 没有 主键 ， 
A A MBG 将 不 会 生成 update by primary key 方 法 ) 。 


e Java 客 户 端 类 会 适当 的 使 用 上 面 的 对 象 ， 生 成 Java 客 户 端 类 时 可 选 的 。MBG 
会 为 MyBatis 3.x 生 成 如 下 客户 端 类 : 


o 一 个 可 以 和 MyBatis 3.x 一 起 使 用 的 mapper 接 口 类 MBG 会 为 BATIS 2.x 生 
成 如 下 的 客户 端 类 : 

o 符合 Spring 框架 的 DAO 类 。 

o 只 使 用 iBATIS SQL 映射 API 的 DAO。 这 种 DAO 可 以 通过 下 面 两 种 方式 生 
成 : 提供 SqlMapClient 通过 构造 方法 或 者 setter 注 入 。 

o 符合 iBATIS DAO 框架 的 DAO (iBATIS 可 选 的 一 部 分 ， 这 一 框架 已 经 过 
时 ， 我 们 建议 您 使 用 Spring 框架 替代 ) 。 


O O O OỌ 0 0 0 0 


MyBatis generator 可 以 在 迭代 开发 环境 中 良好 的 运行 ， 在 持续 的 构建 环境 中 作为 
一 个 ant 任 务 或 maven 插 件 。 运行 MBG 时 要 记 住 以 下 重要 的 事 : 


1. MBG 会 自动 合并 已 经 存在 并 且 和 新 生成 的 文件 重 名 的 XML。MBG 不 会 覆盖 
您 对 已 经 生成 Xml 所 做 的 修改 。 您 可 以 反复 的 运行 而 不 必 担 心 失去 您 自 定 义 的 
更 改 。MBG 将 取代 所 有 以 前 运行 中 生成 的 XML 元 素 。 

2. MBG 不 会 合并 Java 文件 ,他 可 以 覆盖 已 经 存在 的 文件 或 者 保存 新 生成 的 文件 
为 一 个 不 同 的 唯一 的 名 字 。 您 可 以 手动 合并 这 些 更 改 。 当 您 使 用 Eclipse 插件 
时 , MBG 可 以 自动 合并 Java 文件 . 


依赖 项 


MBG 依 赖 JRE, 需 要 JRE6.0 或 以 上 版 本 。 此外， 还 有 一 个 继承 了 
DatabaseMetaData 接 口 的 JDBC 驱 动 。 特别 
是 getColumns 和 getPrimaryKeys 两 个 方法 时 必须 的 。 


通过 Mybatis 用 户 邮件 列表 提供 对 Mybatis generator 的 支持 。 您 可 以 通过 谷歌 订阅 
或 查看 邮件 列表 的 代码 : 
http://groups.google.com/group/mybatis-user 


如 果 您 认为 您 找到 了 一 个 bug， 在 您 创建 新 的 Issue 前 ， 请 在 用 户 列表 中 询问 一 下 。 
如 果 您 发 现 一 个 bug， 或 者 有 新 的 功能 要 求 ， 您 可 以 在 github 上 打开 一 个 新 的 
Issue : 


https://github.com/mybatis/generator/issues 
译 者 


译 者 水 平 有 限 ， 如 果 您 发 现 翻译 不 通顺 的 地 方 ， 您 可 以 在 下 面 的 地 址 创建 lssue : 


http://git.oschina.net/free/mybatis-generator-core/issues 


译 者 列表 


e abel533(isea533) 
o github:https://github.com/abel533 
o gitosc:http://git.oschina.net/free 
o blog:http://blog.csdn.net/isea533 
e hs598375774sa 
o oschina:http://my.oschina.net/hssa 


o ' 十 锦 色 勾 年 华 201? 
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MyBatis Generator 新 增 功能 


Version 1.3.3 
公告 

e MyBatis Generator 需要 JRE 1.6 或 更 高 版 本 的 支持 
改进 


e 从 MyBatis 3.2 开始 使 用 了 新 的 SQL 生成 器 类 。 如 果 您 必须 在 MyBatis 旧版 
本 上 运行 ， 在 您 的 < JavaClientGenerator > 配置 上 设置 属 
性 "useLegacyBuilder "为 "true" 。 

e Issue #11 - maven 插 件 现在 会 输出 到 maven 日 志 (thanks to Paul Krause) 

e Issue #4 - 如 果 任 何 列 将 解析 为 一 个 Java 保留 字 ， 生 成 器 现在 会 抛 出 一 个 警告 


Bugs 修复 


e Fixed issue #648 - Missing imports when using constructor based models 
e Issues #10 - EqualsHashCodePlugin now uses the java.util.Arrays methods 
for array attributes. 


Version 1.3.2 


Bugs 修复 


e Add comments to generated constructors in the model classes so they can be 
merged. 

e Support package names with Uppercase elements. 

e Fixed issue #288 - Incorrect annotated countByExample method 

e Fixed the Maven plugin so <properties> files can be found in the project 
classpath. 

e Fixed issue #359 - make JdbcTypelnformation public 

e Fixed Context.toxmlElement() method to include missing attributes 

e Fixed CaselnsensitiveLikePlugin to add new methods to GeneratedCriteria 
inner class 

e Issue #412 - update the documentation to reflect the difference in MyBatis3 

regarding generated keys. 

Issue #440 - incorrect code generated for primitives with type handlers 

Issue #439 - use auto boxing for primitives when appropriate 

Issue #438 - keep primary key properties in database sequence 

Issue #507 - RowBounds plugin generates duplicate statements 


e Issue #593 - CaselnsensitiveLikePlugin skipped Jdbc4 National Character 
Types 


改进 


e Added a new target runtime - MyBatis3Simple - that can be used to generate 
very simple CRUD operations on tables. This runtime produces far simpler 
MyBatis code than the normal MyBatis3 runtime. The produced code also has 
lower functionality that the normal MyBatis3 runtime. If you do not regularly 
use the "by example" methods, then the code produced by the MyBatis3Siple 
runtime may be more suitable to your project. 

e Added a new plugin - VirtualPrimaryKey plugin - that can be used to specify 

columns that act as a primary key, even if they are not defined as primary 

keys in the database. 

Issue #328 - Added a new plugin - RowBounds plugin - that will generate an 

additional version of selectByExample that supports the MyBatis 

RowBounds function. 

e Created a new reference page for supplied plugins: Supplied Plugins 

e Issue #368 - Allowed for generation of Java Model only. If no 
SQLMapGenerator or JavaClientGenerator is specified in a context, then only 
a Java Model is generated. Also, if property "modelOnly" is set to "true" on a 
<table> element, then only model object and, possibly XML result maps, will 
be generated. 

e Issue #374 - Allow for specification of a file encoding for reading/writing Java 
files on the file system. There is a new property "javaFileEncoding" on the 
<context> element that can be used to specify a Java file encoding. (XML 
files are always read/written in UTF-8 per the spec). 

e Added the ability to specify custom code formatters for generated Java and 
XML files. See new properties on the <context> element for more information. 

e Added support for varargs to 

org.mybatis.generator.api.dom.java.Parameter class 

e Added support for synchronized and native to 

org.mybatis.generator.api.dom.java.Method class 

e Added support for transient and volatile to 

org.mybatis.generator.api.dom.java.Field class 

e Issue #375 - Added a new plugin - ToStringPlugin - that will generate a 
toString() method in the model classes. Thanks Alexei and Iwao! 

e Issue #233 - added GWT capability to the Serializable plugin 

e Issue #564 - support subpackages at the table level 

e Issue #590 - new plugin for <cache>. Thanks Jason Bennett! 


Version 1.3.1 


Bugs 修复 


e Always specify <selectKey> order for MyBatis3 - position within the <insert> 


is not relevant. 
e "rootinterface" was ignored for XMLMAPPER clients 
e Fixed bug when a lower case class name is specified as a domain object 


name 
e Fixed issue #174 - incorrect format of order by clause in 
selectByExampleWithBlobs 
改进 


e Added a new MyBatis3 generator that generates code based solely on 
annotations with no generated XML. Configuration settings for this new 
generator are as follows: 

o The targetRuntime attribute of <context> element is MyBatis3 
o The type attribute of <javaClientGenerator> element is 
ANNOTATEDMAPPER 

e Added a new MyBatis3 generator that generates code based on a mix of 
annotations and generated XML. Configuration settings for this new generator 
are as follows: 

o The targetRuntime attribute of <context> element is MyBatis3 
o The type attribute of <javaClientGenerator> element is 
MIXEDMAPPER 

e Add support for JDBC types NCHAR, NCLOB, NVARCHAR to match 
MyBatis3. 

e Added support for "useGeneratedKeys" in MyBatis3. See <generatedKey> for 
details. 

e Added support for immutable objects and constructor based result maps in 
MyBatis3. See <table> and/or <javaModelGenerator> for details. 

e Added support for initialization blocks in the Java DOM 

e Issue #214 - Added the ability to supress all comments in generated code. 
See <commentGenerator> for details. 


Version 1.3.0 


1. Moved to mybatis.org, renamed MyBatis Generator 
2. MyBatis generator will continue to support XML configuration files from lbator. 
However, any new features will only be implemented in MyBatis formatted 
configuration files. Some minimal changes are required to migrate lbator 
formatted configuration files to the new DTD for MyBatis Generator. 
3. Configuration settings for MyBatis 3 are as follows: 
i. The targetRuntime attribute of <context> element must be changed 
to MyBatis3 
ii. The type attribute of <javaClientGenerator> element must be changed 
to XMLMAPPER 
4. Removed support for suppressTypeWarnings property in the 
&lt;context&gt; element. This confusing property has become 
unmanagable due to confusion between @SuppressWarnings("unchecked") 


and @SuppressWarnings("rawtypes") in the different compilers. This was 
only used in the corner case where code generated with Ibatis2Java2 
targetRuntime was to be compiled with a JSE 5.0 compiler. 


Version 1.2.2 (Never Released) 


Announcements 


e The org.apache.ibatis.ibator.api.CommentGenerator interface has 
changed. Classes that implement this interface must be changed. With this 
change, implementing classes have access to many more data elements 
from which to generate comments. Additionally, this change makes the 
comment generator interface more consistent with the other public lbator 
interfaces. Details of the change follow: 


o Methods which accepted the parameter FullyQualifiedTable now 

accept the parameter IntrospectedTable instead. The 
FullyQualifiedTable instance is available through the method 
IntrospectedTable. getFullyQualifiedTable( ) 

o Methods which accepted the String parameter columnName now 
accept the parameter IntrospectedColumn instead. The column 
name is available through the method 

IntrospectedColumn.getActualColumnName() . 
重要 提示 : any implementation that subclasses the lbator supplied class 
DefaultCommentGenerator does not need to change immediately with this 
release. The old methods have been deprecated and will be removed with the 
next release of Ibator - so subclasses should be reworked as soon as 
convenient. 


The SQL Map generator has changed in that it no longer prepends the string 
"ibatorgenerated_" to every generated XML id. If you were relying on these 
generated names in other code, you can force lbator to prepend the string 
with the property useLegacyXMLIds_ on the <Sq!MapGenerator> 
configuration. 


e lbator is now built with Maven and includes a Maven plugin 


Bugs 修复 


e NPE when no DAOs are generated. 

e IBATIS-579 - Don't allow column names that contain spaces to break across 
lines in generated XML. 

e Fixed NPE and incorrect calculation in generated equals method (from 
EqualsHashCodePlugin) when certain fields are null - thanks to Benjamin 
Klatt for finding this bug. 

e IBATIS-601 - improper validation of <generatedKey> 


IBATIS-609 - incorrect parsing of Java generic types 

Fixed spelling error LONCVARCHAR to LONGVARCHAR (thanks Allard) 
Fixed IBATIS-731 - change name of primary key variable to avoid conflicts 
Fixed IBATIS-699 - Overwrite unmergeable XML files if enabled 

Fixed issue where insertSelective failed if there is a sequence generating the 
primary key (issue only with iBATIS3) 


改进 


IBATIS-569 - Modified the lbatorRules implementation to make it easier for 

plugins to provide custom implementations of lbatorRules. See the Javadoc 

for the new class 
org.apache.ibatis.ibator.internal.rules.IbatorRulesDelegate for 

more information. 

IBATIS-571 - Added support for automatically delimiting SQL keywords if they 

are used as column names in tables. See the <ibatorContext> page for more 

information. 

IBATIS-577 - Define SQL fragments for column lists to improve reusability of 

generated code. Thanks to Iwao AVE! for the idea and the initial patch. 

Added new -verbose command line argument. See the Running !bator 

page for more information. 

Added logging statements for use in debug. See the Logging page for more 

information. 

Added new example plugin to demonstrate adding case insensitive LIKE 

support to generated Example classes. See the <ibatorPlugin> page for more 

information. 

Added "delimitAllColumns" attribute to table configurations. This supports 

databases like PosgreSQL that are case sensitive for identifiers. See the 

<table> page for more information. 

Added a page explaining how to deal with case sensitivity in PostgreSQL. 

See the PostgreSQL page for more information. 

IBATIS-586 - Added the ability to specify nested property elements on 

columnOverrides. See the <columnOverride> page for more information. 

Thanks to Dan Turkenkopf for the idea and a nice initial patch. 

The IntrospectedColumn class now contains any column remarks returned 

during database introspection. This may be useful for some 

CommentGenerators. 

IBATIS-592 - Added attributes to IntrospectedTable that contain the 

calculated SqiMap namespace, and the calculated runtime table names. 

These can now be overridden in plugins. 

Fixed addCriterionfor JDBC* methods so that they all do a null check. 


e Fixed IbatorRunner so that configuration errors are shown (thanks to Karel 


Rank) 

IBATIS-605 - Added Informix Dialect for <generatedKey> 
Addedd support for "distinct" on select by example methods 
Added new "or" method to example classes 

Added new "useCompoundPropertyNames" property on <table> 


e Enabled a far simpler method for extending the example classes 
e EqualsHashCodePlugin now generates far superior methods 


Version 1.2.1 


Bugs 修复 


e Fixed the lbatorObjectFactory so it will find internal classes from the context 
classloader. 
e Fixed IBATIS-565 - ill formed comment in the SqiMapConfigPlugin 


改进 


e Modified plugin methods for model fields, getters, and setters so that the 
plugin will know which type of class (Primary Key, Base Record, or Record 
with BLOBs) is being generated. 

e Added methods to IntrospectedTable to get/set attributes. This allows plugin 
classes to maintain table based state between plugin calls. 

e Added initialized method to the plugin API. This allows plugins to alter 
some of the fundamental code generation items (like the name of a generated 
class, for example). 

e Added an example plugin to show usage of the initialized method. 


Version 1.2.0 


Announcements 


e With version 1.2, Abator is renamed to Apache iBATIS Ibator. Several 
changes have been made to the XML configuration as well as the Java API. 
See the Migrating from Abator page for detailed information about changes 
needed to existing Abator configuration files. 


Bugs 修复 


e Fixed the JavaTypeResolver so that columns with unsupported data types 
may be overridden by configuration. 

e Fixed IBATIS-523 - a bug in the pre-release version of the 
EqualsHashCodePlugin 

e Fixed IBATIS-542 - upgrade the build to Ant version 1.7.1 


改进 


e lbator now includes a plugin mechanism. This mechanism can be used to add 


to or modify the code generated by lbator. If you have previously extended 

one of Abator's code generators to change their behavior, we strongly 

suggest that you move to a plugin. See the <ibatorPlugin> page for detailed 
information. 

lbator ships with the following plugins: 

o Aplugin that will generate an SQL Map Config File 
( org.apache.ibatis.ibator.plugins.SqlMapConfigPlugin ) 
o Aplugin that will make generated model classes Serializable 
( org.apache.ibatis.ibator.plugins.SerializablePlugin ) 
o Aplugin that will add equals and hashCode methods to generated 
model classes 
( org.apache.ibatis.ibator.plugins.EqualsHashCodePlugin ) 

e Added support for "runtimeCatalog" and "runtimeSchema" properties to the 
<table> configuration element. Thanks to Dan Turkenkopf for the idea and the 
patch! 

e New generated method - insertSelective. This method will allow you to use 
column defaults on a table definition on insert 

e Added the ability to specify a that DAO implementation classes be ina 
separate package from the DAO interface classes. 


Changes from Abator 


There are several breaking changes between Ibator and Abator. This list details 
the changes, and has methods of resolving the differences. 


e JSE 5.0 or higher is required for Ibator 

e lbator does not contain the "legacy" code generators from Abator. You must 
choose "Ibatis2Java2" or "Ibatis2Java5" as a target runtime - and code 
generated from lbator is compatible with iBATIS version 2.2.0 or higher only. 
If you are using an earlier version of iBATIS - upgrade! If you are not able to 
upgrade, then you must continue to use Abator. 

e The classloading strategy in Ibator is changed from Abator. In all cases, we 
now recommend specifying the classpath external to Ibator and we further 
recommend that you do not use the &lt;classPathEntry&gt; element. 
You may specify classpath entries if you feel you must, but those entries will 
only be used when loading JDBC drivers of Java model root classes. If you 
write a custom extension to lbator, or a plugin, you must specify that 
classpath entry external to Ibator. 

e The API for extending Ibator is significantly changed from Abator. In most 
cases, implementations of the old Abator interfaces should be converted to 
Ibator plugins. See the Extending lbator for more information. 

e The afterxXxxGenerationHook methods have been removed from all 
lbator supplied implementations of the core interfaces. If you were extending 
an lbator supplied implementation to make use of these methods, then you 
must migrate your code to an lbator plugin. 

e The build has been significantly modified and now includes an Emma based 
code coverage report. 


e Changes to the XML configuration file are required. See the Migrating from 
Abator page for detailed information 


Version 1.1.0 


Announcements 


e The next release of Abator will require JRE 5.0 or higher. 

e Java2 is now the default generator set. This will cause different code to be 
generated if you have not specified a generator set previously. To remedy 
this, set the generator set to "Legacy". 


New Generated Methods 


Abator will generate these new methods: 
countByExample 


This method will return an integer representing the number of rows in a table that 
match the given criteria. 


updateByExample 


This method will update all rows in a table that match a given criteria. This method 
is available in the Java2 and Javad generator sets only. There is also a "selective" 
version of the method that only updates certain columns of a table (the selective 
version of this method is probably the more useful version to use in most 
situations). 


Bugs 修复 


e Fixed bug for corner case where a criteria class is created, but no criteria are 
set. 

e Fixed a bug that caused the JavaModelGenerator's "trimStrings" property to 
fail 

e Fixed the XML file merger so that internal entities are preserved 

e Fixed the XML configuration parser so that external entities are handled 
properly 

e Fixed bug - incorrect datatype mapping for JDBC BIT datatype 

e Fixed bug where Abator generated incorrect properties for certain database 
columns (for example, if the column name is |_ NAME) 


Miscellaneous Changes 


e Added the ability to specify properties to ignore qualifiers and change runtime 
table names in the generated SQL for a table. Primary use cases for this 


Support include: 

o Generating objects for a table that has a public synonym or alias 

o Generating objects for a table that exists in many schemas, and the 
schema will be selected at runtimeSee the <table> reference page for 
more information, or the Oracle reference page for an example. 

Added support for delimiting SQL identifiers for the use cases where 
identifiers contain spaces or SQL reserved words. See the <table>, 
<abatorContext>, and <columnOverride> reference pages for more 
information. 

Added SYBASE dialect for generated keys. See the <generatedKey> 
reference page for more information. 

Added DB2_MF (DB2 on Main Frames) dialect for generated keys. See the 
<generatedKey> reference page for more information. 

Abator will now automatically escape identifiers that contain the $ or # 
characters as these characters have special meaning in iBATIS configuration 
files. 

Added a clear method to the generated example classes (in the Java2 
and Javad generator sets only). This allows reuse of these classes. 

Added the ability to specify that result maps should use column indexes 
rather than column names in the result mappings. Primary use cases for this 
support include: 

o When tables have columns whose name is only differentiated by case 
(e.g. "first name" and "First Name") 

o When you want to make the selects as fast as possible (there is a slight 
performance benefit when using column indexes)See the <table> 
reference page for more information. 

Made the generated Example and Criteria classes extendable. Added some 

documentation about how to extend these classes. See the Extending the 

Example Classes reference page for more information. 

Made the legacy DAOs extendable. 

Added the ability to provide a renaming rule for columns. This is for the use 

case where columns have a common prefix that should be removed before 

calculating the property name. See the <columnRenamingRule> reference 

page for more information. 

Added support for persisting a configuration to XML - this to enable a 

graphical editor in the future. 

Add afterxXxXXGenerationHook() methods in all generators to enable adding 

extra Java code or XML elements to any generated object. This will make it 

easier to create customized generators. 

API change to allow generating with selected contexts rather than the entire 

config file. 

API change to allow generating with selected tables rather than the entire 

config file. 

Exposed new support for selecting tables and/or contexts to the command 

line and the Ant task - this has added an advanced syntax to the command 

line for Abator. See the Running Abator reference page for more information. 
rootClass and rootInterface may now be specified for each table. 

See the <table> reference page for more information. 


e Ifa rootClass is specified for any table, Abator will now check in the 
rootClass to see if a generated property already exists in the root class. If it 
does, Abator will not generate the property. The <javaModelGenerator> 
element now accepts a property to specify the classpath of the rootClass . 
See the <javaModelGenerator> reference page for more information. Thanks 
to Ashok Madhavan for the beginnings of this code. 

e Allowed specifying a type (pre or post) for the generated key element. See 
the <generatedKey> reference page for more information. 

e Added a comment generator interface to enable generation of custom 
comments. See the <commentGenerator> reference page for more 
information. 


Version 1.0.0 


Generator Sets 


A generator set is a set of code generators (SQL Map Generator, Java Model 
Generator, DAO Generator, and Java Type Resolver). Abator now ships three 
different generator sets. The generated code from these three generator sets is 
slightly different, and the use of the generated objects is slightly different too. The 
concepts are exactly the same. With the newer generator sets, the "by example" 
methods have been vastly improved. It is now possible to generate virtually any 
WHERE clause (including IN and BETWEEN predicates). Lastly, the new 
generator sets generate much more concise code - the DAOs and SQL Maps are 
of normal size, and there are no extraneous methods. The example class in the 
new generator sets encapsulates all the function needed to generate dynamic 
queries. 


The three generator sets shipped with Abator are as follows: 
Legacy 


This generator set generates code that is the same as previous versions of 
Abator. There are some limitations with this generator set and we strongly 
recommend that you choose one of the other sets. However, this set remains the 
default for now. This generator set will likely be removed in a future version 
of Abator. 


Java2 


This generator set generates code that is compatible with iBATIS versions 2.2.0 
and higher. With this generator set the "by example" methods are much more 
powerful than in the legacy set. It is now possible to generate virtually unlimited 
SQL WHERE clauses with Abator generated code (including "IN" and 
"BETWEEN" clauses). This generator set will likely become the default set in 
a future version of Abator. 


Java5 


This generator set has the same capabilities as the Java2 generator set with the 
added feature of generating code that is JSE 5.0 compliant using parameterized 
types and annotations. 


重要 : code generated with the Java2 or Java5 generator sets is not 100% 
compatible with code generated with the Legacy set - especially in the use of the 
"by example" methods. Also note that the "by example" methods in these 
generator sets rely on iBATIS dynamic SQL support that is missing in iBATIS 
versions prior to version 2.2.0. 


A generator set is selected with the generatorSet attribute of the 
&lt;abatorContext&gt; element. See the <abatorContext> reference page for 
more information. 


Use of the example classes is different with the different generator sets. See the 
Example Class Usage page for more information. 


Model Types 


A model type is used to give you more control over the types of domain objects 
generated by Abator. Abator now supports three different types of domain models 
as follows: 


conditional 


This model is similar to the hierarchical model except that a separate class will not 
be generated if that separate class would only contain one field. So if a table has 
only one primary key field, that field will be merged into the base record class. 
This model type is the default. Note that this model type may generate classes 
that are not 100% with classes generated in previous versions of Abator. 


flat 


This model generates only one domain class for any table. The class will hold all 
fields in the table. 


hierarchical 


This model is the same as the model shipped with the initial versions of Abator. 
This model will generate a primary key class if the table has a primary key, 
another class that holds any BLOB columns in the table, and another class that 
holds the remaining fields. There is an appropriate inheritance relationship 
between the classes. 


Model types can be specified as a default for an entire context, and you may 
override the default for each table in a context. See the <abatorContext> 
reference page for more information about setting the context default.. See the 
<table> reference page for more information about setting a model type for 
specific tables. 


重要 : the default value is conditional - this is a non-backward compatible change 
from previous versions of Abator. 


updateByPrimaryKeySelective 


This is anew mapped SQL statement, and new DAO method, that will only update 
columns whose corresponding properties in the parameter class are non-null. This 
can be used to update certain columns in a record without needing to update the 
entire record. 


重要 : any column that is mapped to a primitive type will always be updated. 


Miscellaneous Changes 


Added the ability to specify a table alias. This aids in reuse of generated SQL 
map elements. See the <table> reference page for more information. 

Fixed the XML file merger so that extraneous blank lines at the end of the file 
are removed. 

Added the ability to specify a type handler for table columns. See the 
<columnOverride> reference page for more information. 

Added the ability to specify the visibility of the DAO "by example" methods. 
This allows you to make the methods private for internal use only. See the 
<javaClientGenerator> reference page for more information. 

Added the ability to override the naming convention for DAO method names. 
See the <javaClientGenerator> reference page for more information. 

Added the ability to specify wildcards for schema or tableName in a table 
configuration. This will allow generation of many tables with a simple XML 
configuration. See the <table> reference page for more information. 

Added the ability to escape wildcard characters in schema or table names if 
required by the driver. See the <table> reference page for more information. 
Added the ability to suppress JSE 5.0 type warning messages for non- 
parameterized types if you are using the Legacy or Java2 generator sets in a 
JSE 5.0 environment. See the <abatorContext> reference page for more 
information. 

Added the ability to specify an external properties file for passing parameters 
into an Abator configuration file (like the iBATIS properties file). See the 
<properties> reference page for more information. 

The Ant task now supports a "verbose" attribute. See the Running Abator 
page for more information. 

The Ant task now supports a nested property set for passing values into an 
Abator configuration file. See the Running Abator page for more information. 


MyBatis Generator 快速 入 门 指南 


若 要 局 动 并 快速 运行 MyBatis Generator (MBG) ， 请 按 以 下 步骤 进行 : 
1. 创建 并 填写 适当 的 配置 文件 。 至少 ， 您 必须 指定 


i. &lt;jdbcconnection&gt; 元 素 定 义 如 何 连 接 目标 数据 库 

i. &lt;javaModelGenerator&gt; 元 素来 指定 生成 Java 模型 对 象 所 属 的 
包 

ii. &lt;sqlMapGenerator&gt; 元 素来 指定 生成 SQL 映射 文件 所 属 的 包 和 
的 目标 项 目 

iv. (可 选 的 ) &lt;javaClientGenerator&gt; 元 素来 指定 目标 包 和 目标 项 
目 生成 的 客户 端 接口 和 类 (如 果 您 不 想 生 成 Java 客户 端 代码 您 可 以 省 
略 &lt; javaClientGenerator &gt; 元 素 ) 

查看 XML 配置 文件 参考 一 个 配置 文件 的 例子 . 


2. 将 文件 保存 在 一 些 方便 的 位 置 (例如 \temp\generatorConfig.xml) 
3. 按 下 面 的 方式 从 命令 行 运行 MBG: 


java -jar mybatis-generator-core-x.x.x.jar -configfile 
\temp\generatorConfig.xml -overwrite 


告诉 MBG 使 用 配置 文件 去 运行 。MBG 还 会 覆盖 已 经 存在 的 同名 Java 文 
如 果 您 想 保 留 已 经 存在 的 Java 文 件 ， 您 可 以 忽略 -overwrite 参数 。 
如 果 存 在 冲突 , MBG 会 用 一 个 唯一 的 名 字 保 存 新 生成 的 文件 〈 例 如 : 
MyClass.java.1) ° 


4. MBG 运 行 后 , 您 将 需 建 或 修改 的 标准 MyBatis 或 iBATIS 配置 o 
新 生成 的 代码 。 查 看 运 MyBatis Generator 后 的 任务 页 面 获取 更 多 信 ， 


重要 :为 BATIS2 生 成 的 代码 需要 在 您 的 BATIS 配置 中 启用 了 该 命名 空间 。 查看 运 
行 MyBatis Generator 后 的 任务 页 面 获取 更 多 信息 。 


运行 MyBatis Generator 


MyBatis Generator (MBG) 可 以 通过 以 下 方式 运行 : 


从 命令 提示 符 使 用 XML 配置 文件 
作为 Ant 任务 使 用 XML 配置 文件 
作为 Maven Plugin 
从 另 一 个 Java 程序 使 用 XML 配置 文件 


每 种 方法 的 详细 信息 都 在 链接 的 页 面 上 。 


注意 :还 有 一 个 可 以 良好 的 集成 到 Eclipse 的 MBG 插 件 可 以 提供 额外 的 功能 。 Eclipse 
启用 Ant ie 并 支持 Java 文件 的 自动 合并 。 安 装 Eclipse 插 件 请 参考 MyBatis 站 
点 页 面 的 信 ， 


重要 : 当 运 行 在 像 Eclipse 这 样 的 IDE 环 境 的 外 部 运行 时 , MBG 解 释 targetProject 
和 targetPackage 的 所 有 XML 属性 如 下 


e targetProject 被 假定 为 一 个 已 存在 的 目录 结构 。 如 果 目 录 结 构 不 存在 
MBG 将 会 失败 。 有 一 个 例外 - 当 MBG 通 过 Maven 插 件 运 行 时 。 请 从 Maven 插 
件 页 面 参阅 targetProject D o 

e targetPackage 将 会 转换 为 targetProject 适当 的 子 目 录 结 构 。 如果 有 
必要 ，MBG 会 创建 这 些 子 目录 。 


从 命令 行 运行 MyBatis Generator 


MyBatis Generator (MBG) 可 以 直接 从 命令 行 运行 。JAR 清 单 包括 默认 类 的 名 称 
( org.mybatis.generator.api.ShellRunner ) 或 者 您 可 以 自己 指定 它 。 
ShellRunner 类 接受 以 下 的 几 种 详细 参数 : 


参数 值 


LH) ATE 指定 配置 文件 的 名 称 。 

如 果 指 定 了 该 参数 ， 如 果 生 成 的 java 文 件 存在 已 经 同名 
的 文件 ， 新 生成 的 文件 会 覆盖 原 有 的 文件 。 如果 没 有 指 
定 该 参数 ， 如 果 存 在 同名 的 文件 ，MBG 会 给 新 生成 的 代 
码 文 件 生 成 一 个 唯一 的 名 字 ( 例 如 : MyClass.java.1， 
MyClass.java.2 等 等 )。 重要 : 生成 器 一 定 会 自动 合并 或 
和 覆盖 已 经 生成 的 XML 文件 。 


-overwrite (可 选 的 ) 


-Verbose (可 选 的 ) 如 果 指 定 该 参数 ， 执 行 过程 会 输出 到 控制 台 。 
-forceJavaLogging 如 果 指 定 该 参数 ，MBG 将 会 使 用 JAVA 日 志 记 录 而 不 会 
(可 选 的 ) 使 用 Log4J, 即 使 Log4J 在 运行 时 的 类 路 径 中 。 

如 果 指 定 了 该 参数 ， 过 号 隔 开 的 这 些 context 会 被 执行 。 
-Contextids 这 些 指定 的 context 必 须 和 配置 文件 中 <context> 元 素 的 
context1,context2,... id 属性 一 致 。 只 有 指定 的 这 些 contextid 会 被 激活 执 
(可 选 的 ) 行 。 如 果 没 有 指定 该 参数 ， 所 有 的 context 都 会 被 激活 执 

行 。 


如 果 指 定 了 该 参数 ， 吉 号 隔 开 的 这 个 表 会 被 运行 ， 这些 
表 名 必须 和 <table> 配置 中 的 表面 完全 一 致 。 只 有 指定 
的 这 些 表 会 被 执行 。 如 果 没 有 指定 该 参数 ， 所 有 的 表 都 
会 被 执行 。 按 如 下 方式 指定 表明 : table 

schema .table catalog..table 等 等 。 


-tables table7, 
table2,... (可 选 的 ) 


从 命令 行 运 行 MGB 时 您 必须 指定 XML 配置 文件 。 如 果 文 件 的 名 字 
是 "generatorConfig.xml", 可 以 用 下 面 任意 的 命令 执行 : 


java -jar mybatis-generator-core-x.x.x.jar -configfile genera 
torConfig. xml 

java -jar mybatis-generator-core-x.x.x.jar -configfile genera 
torConfig.xml -overwrite 

java -cp mybatis-generator-core-x.x.x.jar org.mybatis.generat 
or.api.ShellRunner -configfile generatorConfig. xml 

java -cp mybatis-generator-core-x.x.x.jar org.mybatis.generat 
or.api.ShellRunner -configfile generatorConfig.xml -overwrite 


运行 MyBatis Generator 
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使 用 Ant 运 行 MyBatis Generator 


MyBatis Generator (MBG) 包含 一 个 简 Ant 任务 。 这 个 任 务必 须 定义 在 您 的 
build.xml 文件 中 。 任 务 可 以 几 个 参数 。 这 里 是 一 个 build.xml 文件 的 例子 


<project default="genfiles" basedir="."> 
<property name="generated.source.dir" value="${basedir}" /> 


<target name="genfiles" description="Generate the files"> 
<taskdef name="mbgenerator" 
classname="org.mybatis.generator.ant.GeneratorAn 
tTask" 
classpath="mybatis-generator-core-x.x.x.jar" /> 
<mbgenerator overwrite="true" configfile="generatorConfig 
.xml" verbose="false" > 
<propertyset> 
<propertyref name="generated.source.dir"/> 
</propertyset> 
</mbgenerator> 
</target> 
</project> 


MyBatis Generator 任务 属性 如 下 
属性 值 


ee NO 
如 果 指 定 了 该 参数 ， 如 果 生 成 的 java 文 件 存 在 已 经 同名 的 文件 ， 新 
sverwrite 生成 的 文件 会 覆盖 原 有 的 文件 。 如 果 没有 指定 该 参数 ， 如 果 存在 
(可 选 的 ) 同名 的 文件 ，MBG 会 给 新 生成 的 代码 文件 生成 一 个 唯一 的 名 字 ( 例 
如 : MyClass.java.1, MyClass.java.2 等 等 )。 重要 : 生成 器 一 只 
会 自动 合并 或 覆盖 已 经 生成 的 XML 文件 。 


如 果 指 定 了 该 参数 ， 吉 号 隔 开 的 这 些 context 会 被 执行 。 这 些 指 定 
contextids ”的 context 必 须 和 配置 文件 中 <context> THM id 属性 一 致 。 
(可 选 的 ) 只 有 指定 的 这 些 contextid 会 被 激活 执行 。 如 果 没 有 指定 该 参数 ， 

所 有 的 context 都 会 被 激活 执行 。 


如 果 指 定 了 该 参数 ， ea ， 这 些 表 名 必须 
tables (可 f <table> 配置 中 的 表面 完全 一 致 。 只 有 指定 的 这 些 eer 
选 的 ) 行 。 如 果 没 有 指定 该 参数 ， 所 有 的 ae o 按 如 下 方式 指 


定 表 明 : table schema.table catalog..table 等 等 。 


verbose 如 果 设置 为 "true", "yes" 等 等 ,MBG 会 将 操作 信息 输出 到 ant 控制 
(可 选 的 ) 台 (如 果 Ant 在 verbose 模 式 下 运行 )。 黑 认 值 是 "false" ° 


<taskdef> 标 记 中 的 类 路 径 用 于 告诉 Ant MBG JAR 文件 在 哪里 。 这 是 可 选 
的 ， 除 非 您 将 MBG 添加 到 Ant 类 路 径 中 Ant 手册 所 描述 的 其 他 地 方 。 
任务 的 名 称 可 以 使 任何 您 想 要 的 , "mbgenerator" 只 是 一 个 简单 的 例子 。 

GIES XI TAKEN &lt; propertyset &gt; 元 素 ， 这 是 标准 的 Ant 属 

性 设置 的 类 型 。 这 可 以 用 于 将 参数 传递 到 配置 文件 。 例 如 ， 上 面 提 到 
generated.source.dir 这 个 属性 可 以 在 配置 文件 中 使 

用 ${generated.source.dir} 进行 使 用 。 

如 果 没 有 指定 配置 文件 中 的 一 个 属性 ， 这 个 属性 将 会 原样 输出 。 


通过 Maven 运 行 MyBatis Generator 


MyBatis Generator (MBG) 包含 了 一 个 可 以 集成 到 Maven 构 建 的 Maven 插 件 ， 按 昭 
Maven 的 配置 惯例 , 将 MBG 集 成 到 Maven 很 容易 . 最 简 配 置 如 下 : 
<project ...> 
<build> 
<plugins> 
<plugin> 
<groupId>org.mybatis.generator</groupId> 
<artifactId>mybatis-generator-maven-plugin</artifact 
Id> 
<version>1.3.0</version> 
</plugin> 
</plugins> 
</build> 


</project> 
当然 ， 事 情 永 远 不 会 那么 容易 ! 


Maven Goal and Execution (Maven 目标 和 执行 ) 


The MBG Maven plugin 包含 一 个 目标 : 
e mybatis-generator:generate 
这 个 目标 不 会 被 Maven 自 动 执行 ， 他 可 以 通过 以 下 两 种 方式 执行 。 
可 以 在 命令 行 通过 以 下 命令 执行 : 
e mvn mybatis-generator:generate 
您 可 以 通过 标准 的 Maven 命 令 属性 传递 参数 ， 例 如 : 
e mvn -Dmybatis.generator.overwrite=true mybatis-generator:generat 
这 条 命令 会 使 MBG 履 盖 重 名 的 文件 


在 一 个 连续 的 编译 环境 中 ， 您 可 能 想 让 MGB 作 为 Maven 构 建 的 一 部 分 自动 执行 。 
这 可 以 通过 配置 自动 执行 的 目标 来 实现 ， 这 种 情况 的 例子 如 下 : 


<project ...> 
<build> 
<plugins> 
<plugin> 
<groupiId>org.mybatis.generator</groupId> 
<artifactId>mybatis-generator -maven-plugin</artifact 
Id> 
<version>1.3.0</version> 
<executions> 
<execution> 
<id>Generate MyBatis Artifacts</id> 
<goals> 
<goal>generate</goal> 
</goals> 
</execution> 


</executions> 
</plugin> 


</plugins> 
</build> 
</project> 
MBG} AHR Ea Maventy #49 generate-sources 阶段 。 所 以 他 会 在 编译 


步骤 之 前 执行 。 此 外 注意 MBG 目 标 将 绑 定 生成 Java 和 XML 资源 文件 的 建立 ， 他 们 
都 将 包括 在 生成 的 JAR 包 内 。 


MyBatis Generator 配置 属性 


所 有 配置 在 POM 中 的 属性 都 可 以 传递 到 配置 文件 ， 并 且 可 以 用 通常 的 方式 使 用 。 例 
he: 


<project ...> 


<properties> 
<dao.target.dir>src/main/java</dao.target.dir> 
</properties> 


<build> 
<plugins> 
<plugin> 
<grouplId>org.mybatis.generator</groupId> 
<artifactId>mybatis-generator -maven-plugin</artifact 
Id> 
<version>1.3.0</version> 
<executions> 
<execution> 
<id>Generate MyBatis Artifacts</id> 
<goals> 
<goal>generate</goal> 
</goals> 
</execution> 
</executions> 
</plugin> 
</plugins> 
</build> 


</project> 
在 这 种 情况 下 ， 属 性 可 以 在 配置 文件 中 被 访问 的 语法 是 $f{fdao.target.dir} . 
参考 参数 
所 有 的 参数 都 是 可 选 的 ， 大 部 分 都 适合 的 默认 值 。 


参数 表达 式 类 型 


configurationFile | ${mybatis.generator.configurationFile} java.io.File 


contexts ${mybatis.generator.contexts} java.lang.String 


jdbcDriver ${mybatis.generator.jdbcDriver} java.lang.String 


jdbcDriver ${mybatis.generator.jdbcDriver} java.lang.String 


jdbcPassword ${mybatis.generator.jdbcPassword} java.lang.String 
jdbcURL ${mybatis.generator.jdbcURL} java.lang.String 
jdbcUserld ${mybatis.generator.jdbcUserld} java.lang.String 


outputDirectory ${mybatis.generator.outputDirectory} java.io.File 


overwrite ${mybatis.generator.overwrite} boolean 
sqlScript ${mybatis.generator.sqlScript} java.lang.String 
tableNames ${mybatis.generator.tableNames} java.lang.String 
verbose ${mybatis.generator.verbose} boolean 


targetProject 解释 


与 Maven 运 行 时 生成 器 配置 的 targetProject 属性 有 不 同 的 解释 。 如 果 指 定 值 
为 "MAVEN" (大 小 写 敏感 )，targetProject 将 被 设置 为 插件 的 输出 目录 ， 而 且 如 
果 不 存 在 这 个 目录 ， 将 会 创建 这 个 目录 。 如 果 没 有 设置 为 "MAVEN'", 那 

A targetProject 将 会 被 MGB 当成 普通 的 - 它 必 须 是 一 个 已 经 存在 的 目录 。 


通过 Maven 运 行 MyBatis Generator 
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使 用 Java 运 行 MyBatis Generator 


MyBatis Generator (MBG) 可 以 直接 使 用 Java 调 用 。 对 于 配置 ， 您 可 以 使 用 XML 配 
置 文件 ， 或 者 完全 使 用 Java 进 行 配置 。 


使 用 XML 配置 文件 从 Java 运 行 MBG 


下 面 的 代码 例子 展示 了 如 何 通过 XML 配置 文件 从 Java 运 行 MBG。 LA LRH HA 
理 ， 但 是 编译 错误 是 很 明显 的 :) 


List<String> warnings = new ArrayList<String>(); 

boolean overwrite = true; 

File configFile = new File("generatorConfig.xml"); 

ConfigurationParser cp = new ConfigurationParser (warnings); 

Configuration config = cp.parseConfiguration(configFile); 

DefaultShellCallback callback = new DefaultShellCallback(over 
write); 

MyBatisGenerator myBatisGenerator = new MyBatisGenerator (conf 
ig, callback, warnings); 

myBatisGenerator.generate(null); 


。 配置 文件 属性 可 以 通过 ConfigurationParser 的 构造 函数 的 参数 传递 给 解析 
。 如 果 没 有 显 式 传递 ， 配 置 文件 的 属性 将 会 从 JVM 的 系统 属性 搜索 。 例如 ， 
属性 generated.source.dir 可 以 在 配置 文件 中 通过 
${generated.source.dir} 被 访问 。 
e 如 果 没 有 指定 配置 文件 中 的 一 个 属性 ， 这 个 属性 将 会 原样 输出 。 


通过 基于 Java 的 配置 运行 MGB 


下 面 的 代码 例子 展示 了 如 何 通过 基于 Java 的 配置 运行 MGB。 他 不 显示 异常 处 理 ， 
但 是 编译 错误 是 很 明显 的 :) 


List<String> warnings = new ArrayList<String>(); 
boolean overwrite = true; 
Configuration config = new Configuration(); 


// ... fill out the config object as appropriate... 


DefaultShellCallback callback = new DefaultShellCallback(over 
write); 

MyBatisGenerator myBatisGenerator = new MyBatisGenerator (conf 
ig, callback, warnings); 

myBatisGenerator.generate(null); 


运行 MyBatis Generator 后 的 任务 


在 您 运行 MyBatis Generator (MBG) 后 , 您 需要 创建 或 者 修改 其 他 的 MyBatis 或 
iBATIS 配置 文件 。 主要 的 任务 如 下 : 


e 对 MyBatis 3.x: 
建 或 修改 MapperConfig.xml 文件 
e 对 iBATIS 2.x: 
o 创建 或 修改 SqlMapConfig.xml 文件 
建 或 修改 dao.xml 文件 (只 有 当 您 使 用 iBATIS DAO 框架 时 ) 


下 面 将 详细 地 介绍 每 个 任务 。 


更 新 MapperConfig.xml 文件 (MyBatis 3.x) 


MyBatis x 使 用 了 一 个 XML 文件 , 通常 的 名 字 是 MapperConfig.xml ,声明 数据 
库 连 接 信息 , 事务 管理 方案 , 和 将 会 用 在 MyBatis 会 话 中 的 XML mapper 文件 。 

MBG ze 您 创建 这 个 文件 ， 因 为 它 对 您 执行 环境 一 无 所 知 。 然 而 ， 一 些 在 此 文 
件 中 的 项 目 直接 涉及 MBG 生成 项 目 。 请 参阅 标准 MyBatis 数据 映射 开发 指南 有 关 
不 同 的 配置 选项 的 详细 信息 。 


MBG 具体 需要 在 配置 文件 中 的 有 如 下 
e 必须 列 出 MBG 生成 的 XML 映射 文件 


例如 ,假设 MBG 已 经 生成 一 个 名 为 MyTableMapper.xml 的 XML 了 映射 文件 , 并 且 该 文 
件 已 经 在 您 的 项 目的 test.xml 包 中 。 MapperConfig.xml 文件 应 该 有 这 些 条 
目 : 


<?xml version="1.0" encoding="UTF-8"?> 

<!DOCTYPE configuration 
PUBLIC "-//mybatis.org//DTD Config 3.0//EN" 
"http://mybatis.org/dtd/mybatis-3-config.dtd"> 


<configuration> 
<!-- 安装 适合 于 您 的 环境 的 事务 管理 器 和 数据 源 --> 
<environments default"..."> 
<environment id"..."> 
<transactionManager type="..."> 
</transactionManager> 
<dataSource type="..."> 
</dataSource> 
</environment> 
</environments> 


<mappers> 
<!-- XML mapper 文件 应 该 在 这 里 列 出 来 --> 
<mapper resource="test/xml/MyTable_SqlMap.xml" /> 
</mappers> 


</configuration> 


如 果 有 多 个 XML mapper 文 件 (这 很 常见 ) ， 然 后 您 可 以 通过 反复 的 使 
用 &lt;mapper&gt; 按 任意 顺序 在 alt;mappers&gt; 元 素 中 列 出 这 些 文 件 。 


生成 MapperConfig.xml 您 可 能 会 要 MBG 使 用 MapperConfigPlugin 生 成 一 个 
Mapper 配 置 文件 的 骨架 。 查看 < 插件 > 页 面 获取 详细 信息 。 


Updating the SqiMapConfig.xml File (iBATIS 2.x) 


iBATIS 2 uses an XML file, commonly named SqlMapConfig.xml ,to specify 
information for a database connection, a transaction management scheme, and 
SQL map XML files that will be used in an iBATIS session. MBG cannot create 
this file for you because MBG knows nothing about your execution environment. 
However, some of the items in this file relate directly to MBG generated items. 
Please refer to the standard iBATIS data mapper developer guide for details about 
the different configuration options. 


MBG specific needs in the configuration file are as follows: 


e Statement namespaces must be enabled 
e MBG generated SQL Map XML files must be listed 


For example, suppose that MBG has generated an SQL Map XML file called 
MyTable_SqlMap.xml1 , and that the file has been placed in the test.xml 
package of your project. The SqlMapConfig.xm1_ file should have these entries: 


<?xml version="1.0" encoding="UTF-8"?> 

<!DOCTYPE sqlMapConfig 
PUBLIC "-//ibatis.apache.org//DTD SQL Map Config 2.0//EN" 
"http://ibatis.apache.org/dtd/sql-map-config-2.dtd"> 


<sqlMapConfig> 
<!-- Statement namespaces are required for MBG --> 
<settings useStatementNamespaces="true" /> 


<!-- Setup the transaction manager and data source that are 
appropriate for your environment 
T 
<transactionManager type="... "> 
<dataSource type="... "> 
</dataSource> 
</transactionManager> 


<!-- SQL Map XML files should be listed here --> 
<sqlMap resource="test/xml/MyTable_SqlMap.xml" /> 


</sqlMapConfig> 


If there is more than one SQL Map XML file (as is quite common), then the files 
can be listed in any order with repeated &1t;sqlMap&gt; elements after the 
&lt;transactionManager&gt; element. 


Version 1.2 New Enhancement With MBG version 1.2 and later, You may ask 
MBG to generate a skeleton SQL Map Configuration file with the 
SqlMapConfigPlugin. See the <plugin> page for more information. 


Updating the dao.xml File (iBATIS 2.x) 


重要 提示 : this step is only required if you generated DAOs for the deprecated 
iBATIS DAO framework (we suggest using Spring instead). 


The iBATIS DAO framework is configured by an xml file commonly called 
dao.xml . The iBATIS DAO framework uses this file to control the database 
connection information for DAOs, and also to list the DAO implementation classes 
and DAO interfaces. In this file you should specify the path to your 
SqlMapConfig.xml file, and all the MBG generated DAO interfaces and 
implementation classes. 


For example, suppose that MBG has generated a DAO interface called 

MyTableDAO anda implementation class called MyTableDAOImp1 , and that the 
files have been placed in the test.dao package of your project. The dao. xml 
file should have these entries: 


<?xml version="1.0" encoding="UTF-8"?> 

<!DOCTYPE daoConfig 
PUBLIC "-//ibatis.apache.org//DTD DAO Configuration 2.0//EN" 
"http://ibatis.apache.org/dtd/dao-2.dtd"> 


<daoConfig> 
<context> 
<transactionManager type="SQLMAP"> 
<property name="SqlMapConfigResource" 
value="test/SqlMapConfig.xm1l"/> 
</transactionManager> 


<!-- DAO interfaces and implementations should be listed h 
ere --> 
<dao interface="test.dao.MyTableDAO" 
implementation="test.dao.MyTableDAOImp1" /> 


</context> 
</daoConfig> 


Migrating from lbator 


This page details changes between MyBatis Generator (MBG) and Ibator. For 
most users, the changes should be simple. If you extended any of Ibator's classes 
to supply custom implementations of code generators or the Java type resolver, 
you will need to rework those custom classes. 


Changes are described assuming you are using XML configuration for MBG. If 
you are using Java based configuration, then the changes are still required and 
should be easy to deduce from the description of the XML changes. 


重要 提示 : MBG will correctly parse older Ibator configuration files, so no change is 
actually required. However, new features will only be implemented in configuration 
files that conform to the MyBatis Generator DTD. 


Required for Some Users 
e The DTD has changed. The new DOCTYPE should be 


&lt; !DOCTYPE generatorConfiguration 
PUBLIC "-//mybatis.org//DTD MyBatis Generator Configuratio 
n 1.0//EN" 
"http://mybatis.org/dtd/mybatis-generator-config 1 0.dtd"& 


gt; 


e MyBatis3 is now the default target runtime. 


e The &lt;ibatorConfiguration&gt; element is renamed to 
&1t;generatorConfigurationggt; 
e The &lt;ibatorContext&gt; elementis renamed to &lt;contextégt; 
e The &lt;ibatorPlugin&égt; elementis renamed to &1lt;plugin&gt; 
e The &lt;daoGenerator&gt; element is renamed to 
&lt; javaClientGeneratorégt; 
e If you implemented a plugin, the daoxxx methods have been renamed to 
clientXXX . 


Migrating from Abator 


This page details changes between MyBatis Generator (MBG) and Abator. For 
most users, the changes should be simple. If you extended any of Abator's 
classes to supply custom implementations of code generators or the Java type 
resolver, you will need to rework those custom classes. 


The changes are listed in three categories: from required configuration changes to 
less common changes. Note that most changes are described assuming you are 
using XML configuration for MBG. If you are using Java based configuration, then 
the changes are still required and should be easy to deduce from the description 
of the XML changes. 


Required for All Users 


e The DTD has changed. The new DOCTYPE should be 


&lt; !DOCTYPE generatorConfiguration 
PUBLIC "-//mybatis.org//DTD MyBatis Generator Configuratio 
n 1.0//EN" 
"http://mybatis.org/dtd/mybatis-generator-config 1 0.dtd"& 
gt, 


e The &lt;abatorConfiguration&gt; element is renamed to 
&1t;generatorConfigurationéggt; 


e The &lt;abatorContexté&gt; elementis renamed to &lt;contextégt; 
e The &lt;daoGenerator&gt; element is renamed to 
&1t; javaClientGeneratorégt; 


Required for Many Users 


e MyBatis3 is now the default target runtime. 

e &lt;context&gt; element now requires an ID 

e The generatorSet attribute is removed from the &1lt;context&gt; 
element and replaced with the targetRuntime attribute. Valid values for 
this attribute are Ibatis2Java2 , Ibatis2Java5 ,or MyBatis3 .MBG 
does not include the legacy generator set from Abator - so iBATIS version 
2.2.0 or higher is required for the code generated by MyBatis Generator. 

e The MBG classloading strategy has changed substantially, and we now 
recommend that you manage the runtime classpath external to MBG. If you 
manage the classpath with configuration entries, you must make the following 
changes from Abator: 


o Class path entries are specified at the configuration file level with the 
<classPathEntry> element - now a child element of 
&lt;generatorConfiguration&gt; only. 
o A &lt;classPathEntry&gt; element is not longer allowed as a child 
of &1t;jdbcConnectionégt; 
o The "rootClasspath" property is no longer valid for the 
&1lt; javaModelGeneratoré&gt; element. 


Rarely Required Changes 


e The type attribute is removed from both the 
&lt; javaModelGeneratoré&gt; and &lt;sqlMapGeneratorégt; 
elements. MBG has an entirely different method of supplying custom code 
generators than Abator. See the Extending MyBatis Generator page for full 
details. 

e The JavaTypeResolver interface has changed and is simplified. If you 
specified a custom implementation on the &lt;javaTypeResolverégt; 
element, you must rework your implementation class. 

e The ProgressCallback interface has changed significantly. If you 
implemented this interface for some other execution environment, you will 
need to rework your implementation. 


MyBatis Generator XML 配置 参考 


最 常见 的 用 例 中 ， 代 码 生 成 器 (MBG) 是 由 一 个 XML 配置 文件 驱动 。 配 置 文件 告诉 
MBG: 


o 如 何 连接 到 数据 库 
@ 生成 什么 对 象 ， 以 及 如 何 生成 它们 
。 那些 表 生 成 对 象 


下 面 是 一 个 MBG 配 置 文件 的 例子 。 查 阅 每 个 元 素 单独 的 页 面 查 看 更 多 有 关 元 素 的 更 
多 信息 和 属性 值 。 


<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE generatorConfiguration 
PUBLIC "-//mybatis.org//DTD MyBatis Generator Configuration 1. 
O//EN" 
"http://mybatis.org/dtd/mybatis-generator-config_1 0.dtd"> 


<generatorConfiguration> 
<classPathEntry location="/Program Files/IBM/SQLLIB/java/db2ja 
va.zip" /> 


<context id="DB2Tables" targetRuntime="MyBatis3"> 
<jdbcConnection driverClass="COM.ibm.db2.jdbc.app.DB2Driver" 
connectionURL="jdbc:db2: TEST" 
userId="db2admin" 
password="db2admin"> 
</jdbcConnection> 


<javaTypeResolver > 
<property name="forceBigDecimals" value="false" /> 
</javaTypeResolver> 


<javaModelGenerator targetPackage="test.model" targetProject 
="\MBGTestProject\src"> 
<property name="enableSubPackages" value="true" /> 
<property name="trimStrings" value="true" /> 
</javaModelGenerator> 


<sqlMapGenerator targetPackage="test.xml" targetProject="\M 
BGTestProject\src"> 
<property name="enableSubPackages" value="true" /> 
</sqlMapGenerator> 


<javaClientGenerator type="XMLMAPPER" targetPackage="test.da 
o" targetProject="\MBGTestProject\src"> 
<property name="enableSubPackages" value="true" /> 
</javaClientGenerator> 


<table schema="DB2ADMIN" tableName="ALLTYPES" domainObjectNa 
me="Customer" > 
<property name="useActualColumnNames" value="true"/> 
<generatedKey column="ID" sqlStatement="DB2" identity="tru 
e" /> 
<columnOverride column="DATE_FIELD" property="startDate" / 
> 
<ignoreColumn column="FRED" /> 
<columnOverride column="LONG_VARCHAR_FIELD" jdbcType="VARC 
HAR" /> 
</table> 


</context> 
</generatorConfiguration> 


有 关 此 文件 的 重要 说 明 : 


该 文件 指定 旧式 DB2 CLI 驱 动 程序 将 用 于 连接 到 数据 库 ， 并 指定 在 何 处 可 以 找 
到 驱动 程序 。 
Java 类 型 解析 器 不 应 该 强制 型 对 象 字 段 BigDecimal 的 使 用 ， 这 意味 着 整数 类 型 
( 短 、 整 型 、 长 等 ) 如 果 可 能 的 话 将 被 取代 。 此 功能 是 为 了 使 数据 库 DECIMAL 和 
NUMERIC 列 容易 处 理 。 
Java 模 型 生成 器 应 该 使 用 子 包 。 这 意味 着 在 这 种 情况 下 生成 的 模型 对 象 将 被 放 
置 在 名 为 test.model.db2admin 的 包 中 (因为 表 在 DB2ADMIN schema 
+) 。 如 果 enableSubPackages 属性 设置 为 false ， 那 么 包 名 将 会 是 
test.model ° Java 模 型 生成 器 也 应 该 对 字符 串 进 行 trim 操 作 。 这 意味 着 任 
何 字符 串 属 性 的 setter 方 法 将 调用 trim 方 法 - 如 果 您 的 数据 库 可 能 会 在 字符 末尾 
返回 空白 符 ， 这 是 非常 有 用 的 。 
SQL 了 映射 生成 器 将 使 用 子 包 。 这 意味 着 这 种 情况 下 生成 的 XML 文件 将 被 放置 在 
名 为 test.xml.db2admin 的 包 中 (因为 表 在 DB2ADMIN schema 中 ) ° 如 
果 enableSubPackages 属性 设置 为 false ， 那 么 包 名 将 会 是 
test.xml ° 
DAO 生 成 器 将 使 用 子 包 。 这 意味 着 这 种 情况 下 生成 的 DAO 类 都 会 被 放置 在 名 为 
test.dao.db2admin 的 包 中 (因为 表 在 DB2ADMIN schema 中 ) 。 如果 
enableSubPackages 属性 设置 为 false ， 那 么 包 名 将 会 是 test.dao ° 
DAO 生 成 器 会 生成 一 些 引用 Mybatis XML 配置 的 mapper 接 口 。 
The file specifies only one table will be introspected, but many more could be 
specified. Important notes about the specified table include: 

o The generated objects will be based on the name Customer 
( CustomerKey , Customer , CustomerMapper , etc.) - rather than on 
the table name. 

o Actual column names will be used as properties. If this property were set 
to false (or not specified), then MBG would attempt to camel case the 
column names. In either case, the name can be overridden by the 

&lt;columnOverride&gt; element 

o The column has a generated key, it is an identity column, and the 

database type is DB2. This will cause MBG to generate the proper 

&lt;selectKey&gt; elementin the generated &lt;inserté&gt; 
statement so that the newly generated key can be returned (using DB2 
specific SQL). 

o Thecolumn DATE_FIELD will be mapped to a property called 
startDate . This will override the default property which would be 
DATE_FIELD inthis case, or dateField ifthe 
useActualColumnNames property was setto false . 

o The column FRED will be ignored. No SQL will list the field, and no Java 

property will be generated. 

o The column LONG_VARCHAR_FIELD will be treated as a VARCHAR field, 
regardless of the actual data type. 


<classPathEntry> 元 素 


<classPathEntry> 元 素 用 于 添加 运行 类 路 径 位 置 到 类 路 径 中 的 MyBatis 
Generator (MBG ) e <classPathEntry> Æ% Æ <generatorConfiguration> 的 子 元 
素 . MBG 在 这 些 情况 下 从 这 些 路 径 下 加 载 类 : 


e 当 加 载 JDBC 驱动 内 省 数据 库 时 
e@ 当 加 载 根 类 中 的 JavaModelGenerator 检查 重 写 的 方法 时 


这 个 元 素 是 可 选 的 ， 而 且 如 果 您 给 MGB 安 装 了 类 路 径 ， 您 就 不 需要 这 个 元 素 ( 例 如 
使 用 java 命令 时 使 用 参数 -cp )。 


重要 说 明 : 加 载 扩 展 一 个 MBG 的 类 或 实现 MBG 的 接口 之 一 的 类 时 ， 不 会 使 用 这 些 
位 置 。 在 这 种 情况 下 ， 您 必须 以 相同 的 方式 将 MBG 添加 到 运行 时 的 类 路 径 下 ( 例 
如 使 用 java 命令 时 使 用 参数 -cp )。 


必 选 属性 
属性 描述 
location ”要 添加 到 类 路 径 中 的 JAR/ZIP 文件 的 完整 路 径 名 称 或 要 添加 到 类 路 
ocation 
径 中 的 目录 。 

可 选 属性 
无 
TAR 
无 
例子 


这 里 指定 了 DB2 JDBC 驱 动 的 路 径 : 


<classPathEntry location="/Program Files/IBM/SQLLIB/java/db2java 
serail oh fe? 
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<columnOverride> 71% 


MyBatis Generator (MBG) 使 用 <columnOverride> 元 素 从 将 某 些 属性 默认 计算 的 
值 更 改 为 内 省 数据 库 列 得 的 值 。 这 个 元 素 是 <table> 元 素 可 选 的 一 个 子 元素 。 


必 选 属性 
属性 描述 
column 要 内 省 的 列 名 


可 选 属性 


属性 描述 


要 使 用 的 Java 属性 的 名 称 。 如 果 没 有 指定 ，MBG 会 

根据 列 名 生成 。 例如， 如 果 一 个 表 的 一 列 名 
property A"STRT_DTE" ，MBG 会 根 

据 "useActualColumnNames" 属 性 (查看 <table> 的 属 

性 获取 更 多 的 信息 ) 生成 "STRT_DTE" 或 "strtDte" 。 


该 列 属 性 的 完全 限定 的 Java 类 型 。 如 果 需 要 ， 这 可 
以 覆盖 由 JavaTypeResolver 计算 出 的 类 型 。 对 

javaType 某 些 数据 库 来 说 ， 这 是 必要 的 用 来 处 理 “ 奇 怪 的 ?数据 
库 类 型 (例如 MySql 的 unsigned bigint 类 型 需要 了 映 
射 为 java.lang.Object)。 


该 列 的 JDBC 类 型 (INTEGER, DECIMAL, 
NUMERIC, VARCHAR 等 等 )。 RER’ ATUAR 
盖 由 JavaTypeResolver 计算 出 的 类 型 。 对 某 些 
数据 库 来 说 ， 这 是 必要 的 用 来 处 理 怪异 的 JDBC 驱动 
(例如 DB2 的 LONGVARCHAR 类 型 需要 为 ijBATIS 
映射 为 VARCHAR)。 


用 户 定义 的 需要 用 来 处 理 这 列 的 类 型 处 理 器 。 它 必 
须 是 一 个 继承 iBATIS 的 TypeHandler 类 或 
TypeHandlerCallback 接口 (该 接口 很 容易 继承 ) 
的 全 限定 的 类 名 。 如 果 没 有 指定 或 者 是 空白 ， 
iBATIS 会 用 默认 的 类 型 处 理 器 来 处 理 类 型 。 EB: 
MBG 不 会 校 验 这 个 类 型 处 理 器 是 否 存在 或 者 可 用 。 
MGB 只 是 简单 的 将 这 个 值 插入 到 生成 的 SQL 映射 的 
配置 文件 中 。 


指定 是 否 应 在 生成 的 SQL 分 隔 的 列 名 称 。 如 果 列 的 
名 称 中 包含 空格 ，MGB 会 自动 的 分 割 列 名 ， 所 以 这 
个 重 写 只 有 当 列 名 需要 强制 为 一 个 合适 的 名 字 或 者 列 

RE 名 是 数据 库 中 的 保留 字 时 是 必要 的 。 当 设置 为 "true" 
Æ, colum 属性 用 于 重 写 必须 匹配 从 数据 库 返 回 的 
列 名 。 分 隔 符 指定 在 <context> ARE ° REE 
false。 然 而 MGB 会 自动 分 割 包含 空格 的 列 名 ， 所 以 
在 这 种 情况 下 不 需要 重 写 。 


jdbcType 


typeHandler 


FAR 


e <property> (0..N)  : 在 此 处 定义 的 任何 属性 都 会 被 加 入 相应 的 内 省 列 的 属性 
集合 中 。 MBG 目 前 不 响应 任何 属性 。 此 元 素 被 设置 使 得 对 于 每 一 列 的 特殊 
值 ， 可 以 在 该 插件 被 编码 ， 以 产生 或 修改 一 些 独 特 的 特定 列 中 的 事件 被 提供 给 
插件 。 
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<columnRenamingRule> 7 # 


MyBatis Generator (MBG) 使 用 <columnRenamingRule> 元 素 处 理 在 内 省 表 中 相 
应 的 属性 名 之 前 重 命名 数据 库 列 。 这 对 那些 存在 同一 前 级 的 字段 想 在 生成 属性 名 时 
去 除 前 组 的 表 非 常 有 用 。 例子 ， 假 设 一 个 表 和 包含 以 下 的 列 : 
CUST_BUSINESS NAME 

CUST _ STREET ADDRESS 


CUST_CITY 
CUST_STATE 


生成 的 所 有 属性 名 中 如 果 都 包含 CUST 的 前 级 可 能 会 让 人 不 夹 。 这 些 前 级 可 以 通 
如 下 方式 定义 重 命名 规则 : 


&lt;columnRenamingRule searchString="4CUST_" replaceString="" /&gt; 


注意 ， 在 内 部 ，MBG 使 用 java.util.regex.Matcher.replaceAll 方法 实现 这 
个 功能 。 请 参阅 有 关 该 方法 的 文档 和 在 Java 中 使 用 正则 表达 式 的 例子 。 


4 <columnOverride> 匹配 一 列 时 ， 这 个 元 素 (<columnRenamingRule>) 会 被 急 
略 。<columnOverride> 优 先 于 重 命名 的 规则 。 


如 果 指 定 该 选项 ， 重 命名 规则 会 在 生成 属性 名 前 替换 列 名 。 计算 出 的 属性 名 可 能 不 
同 ， 这 取决 于 <table> 元 素 上 的 "useActualColumnNames'" 属 性 。 下 表 显 示 了 如 果 
重 命名 规则 用 于 字段 集 上 时 不 同 的 值 : 


列 名 属性 
useActualColumnNames="true" UseActual 
CUST_BUSINESS_NAME BUSINESS_NAME businessNi 
CUST_STREET_ADDRESS | STREET_ADDRESS streetAddre 
CUST_CITY CITY city 
CUST_STATE STATE state 


这 个 元 素 是 <table> 元 素 的 一 个 可 选 的 子 元 素 。 


必 选 属性 
属性 描述 
searchString 定义 将 被 替换 的 子 字符 串 的 正则 表达 式 。 


可 选 属性 


属性 描述 


这 是 一 个 用 来 替换 搜索 字符 串 列 每 一 个 匹配 项 的 字符 串 。 如 果 
replaceString ere | 就 会 oe jie 


FAK 


无 


<commentGenerator> AŽ 


<commentGenerator> 元 素 用 来 定义 注释 生成 器 的 属性 。 注释 生成 器 用 来 给 
MyBatis Generator (MBG) 生成 的 多 种 元 素 (Java 自 动 ，Java 方 法 ， 

F) 生成 注释 。 默认 的 注释 生成 器 将 JavaDoc 注释 添加 到 所 有 生成 的 Java 元 素 
ies > 从 而 使 Eclipse 插件 可 以 使 用 合并 Java 的 功能 。 此 外 ， 注 释 还 会 添加 到 每 一 个 
生成 的 XML 元 素 。 注释 的 目的 还 在 于 告诉 用 户 这 个 元 素 是 生成 的 ， 并 且 有 可 能 重新 
生成 (也 就 是 说 - 他 们 不 应 该 被 修改 ) 。 这 个 元 素 是 <context> 元 素 的 一 个 可 选 的 
子 元 素 。 


默认 的 实现 类 是 
org.mybatis.generator.internal.DefaultCommentGenerator ° 如 果 您 只 想 
修改 某 些 行为 ， 默 认 的 实现 类 专门 为 扩展 进行 设计 。 


必 选 属性 

无 

可 选 属性 
属 or 
性 描述 


使 用 用 户 指定 提供 的 注释 生成 器 类 型 。 这 个 类 必须 继 
t 承 org.mybatis. gener SEGT api.CommentGenerator 接口 。 而 且 必 
yp% TUT 函数 。 这 个 属性 接收 指定 特殊 的 值 DEFAULT > 3 
会 使 用 默认 的 实现 类 (这 和 不 指定 该 属性 的 效果 一 样 ) 。 


FAK 


e <property> (0..N) 


支持 的 属性 


这 个 表格 列 出 了 注释 生成 器 中 所 有 可 以 通过 <property> 子 元 素 进行 设置 的 属性 : 


属性 名 


suppressAllComments 


suppressDate 


示例 


属性 值 


这 个 属性 用 来 指定 MBG 生 成 的 代码 中 是 否 包含 任何 注 
Fo 这 个 属性 有 以 下 可 选 值 : 


false 这 是 默认 值 当 这 个 属性 是 false 或 者 没有 指 

时 ， 所 有 生成 的 元 素 都 会 包含 用 来 说 明 这 素 
的 注释 。 

true 当 这 个 属性 是 true 时 ， 不 会 往生 成 的 元 素 中 添加 
任何 注释 。 

敬告: 如 果 您 将 这 个 值 设 为 true， 那 么 所 有 的 代码 合并 
都 会 被 禁用 。 

这 个 元 素 用 来 指定 生成 的 注释 中 是 否 包 含 生成 的 日 
期 。 这 个 属性 有 以 下 可 选 值 : 

false 这 是 默认 值 当 这 个 属性 是 false 或 者 没有 指定 
时 ， 所 有 元 素 生 成 注释 时 都 会 带 着 生成 时 间 。 

true 当 这 个 属性 是 true 时 ， 注 释 中 不 会 添加 时 间 戳 。 


这 个 元 素 指定 了 我 们 不 希望 生成 的 注释 中 包含 时 间 惟 : 


<CommentGenerator> 


<property name="SuppressDate" value="true" /> 


</commentGenerator> 


<Context> 元 素 


<context> 元 素 用 于 指定 生成 一 组 对 象 的 环境 。 子 元 素 用 于 指定 要 连接 到 的 数据 
库 、 要 生成 对 象 的 类 型 和 要 内 省 的 表 。 多 个 <context> 元 素 可 以 在 
<generatorConfiguration> 元 素 中 列 出 来 ， 这 样 可 以 在 同一 个 MyBatis Generator 
(MBG) 从 不 同 的 数据 库 或 者 使 用 不 同 的 生成 生成 器 参数 生成 对 象 。 


必 选 属性 
属性 描述 
id context 唯 一 的 标识 符 。 此 值 将 用 于 某 些 错误 消息 。 
可 选 属性 
属性 描述 


这 个 属性 用 来 设置 生成 对 象 类 型 的 默认 值 ERA 
MBG 如 何 生成 实体 类 。 对 某 些 对 象 关 型 ，MBG 会 给 

detautodellype 表 生 成 一 个 单独 的 实体 类 。 对 另外 一 些 对 象 类 型 ，MI 
据 表 结构 生成 不 同 的 类 。 这 个 属性 有 以 下 可 选 值 : 


conditional 这 是 默认 值 这 个 模型 和 hierarchical 类 似 ， 
果 那 个 单独 的 类 将 只 包含 一 个 字段 ， 将 不 会 生成 一 个 i 
Ko 因此 ,如 果 一 个 表 的 主键 只 有 一 个 字段 ,那么 不 会 > 
段 生 成 单独 的 实体 类 ,会 将 该 字段 合并 到 基本 实体 类 中 


flat 该 模型 为 每 一 张 表 只 生成 一 个 实体 类 。 这 个 实体 类 
表 中 的 所 有 字段 。 


hierarchical 如 果 表 有 主键 ,那么 该 模型 会 产 生 一 个 单 狼 
键 实 体 类 ,如 果 表 还 有 BLOB 字 段 ， 则 会 为 表 生 成 一 个 
有 BLOB 字 段 的 单独 的 实体 类 ,然后 为 所 有 其 他 的 字段 : 
个 单独 的 实体 类 。 MBG 会 在 所 有 生成 的 实体 类 之 间 维 
继承 关系 ( 注 : BLOB 类 继承 其 他 字段 类 继承 主键 


targetRuntime ed ee 代码 的 运行 时 目标 。 该 属性 支 


MyBatis3 这 是 默认 值 使 用 这 值 的 时 候 ，MBG 会 生成 3 
MyBatis 3.0 或 更 高 版 本 ， 兼容 JSE 5.0 或 更 高 版 本 的 3 

(例如 Java 模 型 类 和 Mapper 接 口 会 使 用 泛 型 ) 。 这 上 
对 象 中 的 "by example" 方 法 将 支持 几乎 不 受 限制 的 动 4 
Where 子 句 。 另 外 ， 这 些 生成 器 生成 的 Java 对 象 支持 、 
5.0 特 性 ， 包 含 泛 型 和 注解 。 


MyBatis3Simple 这 是 默认 值 使 用 这 值 的 时 候 ， 和 上 下 
MyBatis3 类 似 ， 但 是 不 会 有 "by example" 一 类 的 方法 
少量 的 动态 SQL。|batis2Java2 使 用 这 值 的 时 候 ，ME 
成 兼容 iBATIS 2.2.0 或 更 高 版 本 (除了 iBATIS 3) ， 还 
Java2 的 所 有 层次 。 这 些 生成 对 象 中 的 "by example"Z 
支持 几 子 不 受 限 制 的 动态 的 where 子 句 。 这 些 生成 的 5 
能 100% 和 原生 的 Abator 或 其 他 的 代码 生成 器 兼容 。 


lbatis2Java5 使 用 这 值 的 时 候 ，MBG 会 生成 兼容 jiBAT 
2.2.0 或 更 高 版 本 (除了 iBATIS 3) ， 兼 容 JSE 5.033 
本 的 对 象 (例如 Java 模 型 类 和 Dao 类 会 使 用 泛 型 ) 。 
成 对 象 中 的 "by example" 方 法 将 支持 几乎 不 受 限制 的 
where 子 2 另外 ， 这 些 生成 器 生成 的 Java 对 BA. 
5.0 特 性 ， 包 含 泛 型 和 注解 。 这 些 生成 的 对 得 不 能 100 
生 的 Abator 或 其 他 的 代码 生成 器 兼容 。 


如 果 您 想 创建 一 个 完全 不 同 的 代码 生成 器 ， 使 用 一 个 
了 org.mybatis.generator.api.IntrospectedTab 
的 权限 定 类 名 替换 该 值 。 通 过 这 个 值 ， 您 可 以 创建 您 
代码 生成 器 ， 然 后 插入 到 代码 生成 器 引擎 中 。 查阅 扩 
MyBatis Generator 页 面 获取 更 多 信息 。 


使 用 这 个 值 去 指定 一 个 继承 

了 org.mybatis.generator.api. we eens 
的 权限 定名 称 。 这 可 以 修改 代码 生成 器 计算 列 信息 时 
为 。 查 阅 扩展 MyBatis Generator 页 面 获 取 更 多 信 息 


introspectedColumnlmpl 


FAR 


<property> (0..N) 

<plugin> (0..N) 
<commentGenerator> (0 or 1) 
<jdbcConnection> (1 Required) 
<javaTypeResolver> (0 or 1) 
<javaModelGenerator> (1 Required) 
<sqlMapGenerator> (0 or 1) 
<javaClientGenerator> (0 or 1) 
<table> (1..N) 


支持 的 属性 


下 面 的 表格 列 出 了 所 有 可 用 的 <property> 子 元 素 : 


属性 名 


autoDelimitKeywords 


beginningDelimiter 


endingDelimiter 


javaFileEncoding 


javaFormatter 


xmlFormatter 


属性 值 


如 果 是 true， 那 么 MGB 会 分 隔 SQL 关 键 字 ， 如 果 他 们 被 用 
的 列 名 。 MBG 维 护 了 许多 不 同 数据 库 的 SQL 关 键 字 列表 
而 ， 列 表 可 能 不 是 非常 的 全 面 。 如果 一 个 特殊 的 关键 字 ? 
MBG 的 关键 字 列 表 中 ， 您 需要 通 

过 &lt;columnOverride&gt; 强制 分 隔 列 。 查 看 
org.mybatis.generator.internal.db.SqlReserved\ 
这 个 类 的 源码 查看 MGB 包含 的 关键 字 列 表 。 默 认 值 是 fals 


要 用 作 需 要 分 a SQL 标识 符 开 头 的 标识 符 分 隔 符 的 ; 
MBG 会 自动 分 割 包含 空格 的 SQL 标识 符 。 MGB 还 会 自动 
<table> 或 <columnOverride> 中 配置 了 具体 要 求 的 标识 名 
值 是 双 引 号 (") 。 


要 使 用 作为 结束 的 标识 符 分 隔 符 需 要 分 隔 符 的 SQL 标识 ; 
MBG 会 自动 分 割 包 BE EA HH SOLARA 。 MGB 还 会 分 隔 
<table> 或 <columnOverride> 中 配置 了 具体 要 求 的 标识 名 
值 是 双 引 号 (") © 


通过 这 个 属性 设置 要 使 用 的 Java 文 件 的 编码 。 新 生成 的 J 
会 用 这 个 编码 写 入 到 文件 系统 。 如 果 Java 文 件 已 经 存在 ; 
使 用 这 个 编码 进行 读 取 ， 就 会 执行 合并 操作 。 如 果 没 有 
会 使 用 平台 的 默认 编码 。 查 阅 java.nio.charset.Char 
取 可 以 选择 的 编码 的 信息 。 


使 用 此 属性 来 指定 生成 的 Java 文件 的 用 户 提供 formater 
的 类 名 称 。 这 个 类 必须 继承 
org.mybatis.generator.api.JavaFormatter mH 
个 默认 (不 含 参 数 ) 的 构造 方法 。 每 一 个 context 都 持 有 - 
的 javaFormatter 的 实例 。 默认 的 javaFormatter 是 
org.mybatis.generator.api.dom.Default JavaFormé 


默认 的 格式 使 用 内 置 到 Java DOME HBX © 


使 用 此 属性 来 指定 生成 的 XML 文件 的 用 户 提 供 formater 
的 类 名 称 。 这 个 类 必须 继承 
org.mybatis.generator.api.XmlFormatter mH 
默认 (KBR) 的 构造 方法 。 每 一 个 context 都 持 有 一 - 
xmlFormatter49 & #] ° 默认 的 xmlIFormatter 是 
org.mybatis.generator.api.dom.DefaultXmlFormat 


默认 的 格式 使 用 内 置 到 Java DOM 类 的 格式 。 


<generatedKey> 1 *# 


<generatedKey> 元 素 用 来 指定 自动 生成 主键 的 属性 (identity 7ft A # sequences 


HAI 


。 如 果 指 定 了 这 个 元 素 ，MyBatis Generator (MBG) 会 在 生成 insert 的 SQL 了 映 
射 文件 中 插入 一 个 合适 的 <selectKey> 元 素 。 这 个 元 素 是 <table> 元 素 的 一 个 可 选 
的 子 元 素 。 


必 选 属性 


sqlStatement 


属性 


column 


描述 
生成 列 的 列 名 。 


将 返回 新 值 的 SQL 语句 。 如 果 这 是 一 个 identity 列 ， 您 可 以 使 用 昌 
A UIR A fi 。 或 者 为 您 的 数据 库 使 用 一 个 合适 的 语句 。 预先 
特殊 值 如 下 


Cloudscape 这 将 转化 为 : VALUES IDENTITY_VAL_LOCAL( ) 
DB2 这 将 转化 为 : VALUES IDENTITY_VAL_LOCAL() 
DB2_MF 这 将 转化 为 "SELECT IDENTITY_VAL_LOCAL() 


FROM SYSIBM.SYSDUMMY1 为 运行 在 ZOS ( 主 框架 ) 或 者 有 1 
iSeries (AS/400) 上 的 DB2 数 据 库 使 用 该 值 


Derby 这 将 转化 为 : VALUES IDENTITY_VAL_LOCAL() 
HSQLDB 这 将 转化 为 : CALL IDENTITY() 


Informix 这 将 转化 为 : 
select dbinfo('sqlca.sqlerrdi') from systables where 


MySql 这 将 转化 为 : SELECT LAST_INSERT_ID() 
SqlServer 这 将 转化 为 : SELECT SCOPE_IDENTITY() 
SYBASE 这 将 转化 为 : SELECT @@IDENTITY 


JDBC 这 会 配置 MBG 使 用 MyBatis3 支 持 的 JDBC 标 准 的 生成 Key 来 
码 。 ave: 立 于 数据 库 获 取 标 识 列 中 的 值 的 方法 。 

重要 : 只 有 当 目 标 运行 为 MyBatis3 时 才 会 产 生 正确 的 代码 。 如 果 : 
一 起 使 用 目标 运行 时 会 产生 运行 时 错误 的 代码 。 


属性 


identity 


描述 
当 设 置 为 true 时 ,该 列 会 被 标记 为 jdentity 列 ， FH 
&lt;selectKey&gt; 元 素 会 被 插入 在 insert 后 面 。 当 设 置 为 
false 时 ， &lt;selectKey&gt; 会 插入 到 insert 之 前 〈 通 常 是 序 
列 ) o SR: 即使 您 type 属性 指定 为 "post" ， 您 仍然 需要 为 
identity 列 将 该 参数 设置 为 "true"。 这 将 标志 MBG 从 插入 列表 中 删除 
ÈP) o RWX false. 
如 果 指 定 ， 则 此 值 将 被 添加 为 生成 selectKey 元 素 的 类 型 。 此 属性 的 
值 应 该 是 "pre" 或 "post"。 重 要 : 如 果 指 定 此 属性 的 值 ， 然 后 生成 
selectKey 元 素 将 永远 被 放置 在 insert 语 句 之前。 


<generatorConfiguration> Z% 


<generatorConfiguration> 元 素 是 MyBatis Generator 配 置 的 根 元 素 。 这 个 文件 必须 
包含 下 面 的 DOCTYPE: 


<!DOCTYPE generatorConfiguration PUBLIC 
"-//mybatis.org//DTD MyBatis Generator Configuration 1.0//EN" 
"http://mybatis.org/dtd/mybatis-generator-config_1 0.dtd"> 


FAK 


e <properties> (0 or 1) 
e <classPathEntry> (0..N) 
e <context> (1..N) 


<ignoreColumn> 元 条 


<ignoreColumn> 元 素 用 来 告诉 MyBatis Generator (MBG) 忽略 一 个 表 中 的 列 。 生 
成 的 SQL 不 会 使 用 该 列 ， 而 且 生成 的 模型 对 象 中 将 不 包含 该 列 。 这 个 元 素 
是 <table> 元 素 的 一 个 可 选 的 子 元 素 。 


必 选 属性 
属性 描述 
column 被 忽略 的 列 名 。 
可 选 属性 
属性 描述 


当 匹 配对 从 数据 库 中 返回 的 列 时 ， 如 果 为 趴 ， 则 
delimitedColumnName ”MBG 将 执行 区 分 大 小 写 完全 匹配 。 如 果 为 false( 默 认 
值 )， 则 被 认为 是 不 区 分 大 小 写 的 名 称 。 


FILE 


<javaClientGenerator> 元 素 


<javaClientGenerator> 元 素 用 于 定义 Java 客户 端 代 码 生 成 器 的 属性 。 Java 客 户 端 
生成 器 生成 Java 接 口 和 类 ， 它 可 以 简单 地 使 用 生成 的 Java 模 型 和 XML 映射 文件 。 
在 iBATIS2 目 标 环境 中 ， 这 些 对 象 可 以 生成 DAO 接 口 和 实现 类 形式 的 代码 。 对 
Mybatis 来 说 ， 会 生成 Mapper 接 口 形式 的 代码 。 这 个 元 素 是 <context> 元 素 的 一 个 
可 选 的 子 元 素 。 如果 不 指定 此 元 素 ， 然 后 代码 生成 器 (MBG) 将 不 会 生成 Java 客 户 端 


接口 和 类 
必 选 属性 


属性 


type 


描述 


此 属性 用 于 选择 一 个 预定 义 的 Java 客 户 端 的 生成 器 ， 或 指定 用 上 
Java 客 户 端 生成 器 。 任 何 用 户 提 供 的 DAO 生 成 器 必须 继承 

org.mybatis.generator.codegen.AbstractJavaClientGen 
类 , 必须 有 一 个 公开 默认 的 构造 函数 。 该 属性 接收 下 列 预 定义 的 
成 器 之 一 : 


如 果 <context> targetRuntime 是 MyBatis3: 


ANNOTATEDMAPPER 生成 的 对 象 是 MyBatis 3.x 映射 器 基础 台 
Java 接 口 。 这些 接 口 将 会 基于 注解 和 MyBatis 3.x SqlProviders 
有 XML 文件 生成 。 ( 注 : 就 是 纯 接 口 使 用 注解 的 形式 ， 不 会 有 X 
件 ) ANNOTATEDMAPPER 依赖 MyBatis 3.0.4 或 更 高 版 本 。 


MIXEDMAPPER 生成 的 对 象 是 MyBatis 3.x 映射 器 基础 结构 的 
口 。 这些 接口 将 基于 注解 和 XML 的 混合 形式 。 注解 将 会 用 在 简 
可 以 实现 的 地 方 。 此 客户 端 不 会 生成 SqlProvider， 所 有 复杂 的 ; 
都 会 生成 在 XML 中 。The MIXEDMAPPER 依赖 MyBatis 3.0.4 : 
pa 


XMLMAPPER 生成 的 对 象 是 MyBatis 3.x 映射 器 基础 结构 的 Ja 
口 。 这 些 接口 将 会 依赖 于 生成 的 XML 文件 。 
如 果 <context> targetRuntime = MyBatis3Simple: 


ANNOTATEDMAPPER 生成 的 对 象 是 MyBatis 3.x 映射 器 基础 台 
Java 接 口 。 这 些 接口 将 会 基于 注解 和 MyBatis 3.x SqlProviders 
有 XML 文件 生成 。 ( 注 : 就 是 纯 接口 使 用 注解 的 形式 ， 不 会 有 X 
件 ) The ANNOTATEDMAPPER 依赖 MyBatis 3.0.4 或 更 高 版 才 
XMLMAPPER 生成 的 对 象 是 MyBatis 3.x 映射 器 基础 结构 的 Ja 
口 。 这 些 接 口 将 会 依赖 于 生成 的 XML 文件 。 


如 果 <context> targetRuntime  Ibatis2Java2 or Ibatis2Java! 
IBATIS 生成 的 对 象 将 符合 〈 不 建议 使 用 ) iBATIS 的 DAO 框 架 。 


GENERIC-Cl 生成 的 对 象 将 只 依赖 于 SqlIMapClient。SqlIMapCli 
通过 构造 参数 依赖 注入 提供 。 生成 的 对 象 将 是 DAO 接 口 和 实现 : 
Ñ o 


GENERIC-SI 生成 的 对 象 将 只 依赖 于 SqlIMapClient。SqlMapcCli 
通过 setter 方 法 依赖 注入 提供 。 生成 的 对 象 将 是 DAO 接 口 和 实现 
人 


SPRING 生成 的 对 象 将 符合 Spring 的 DAO 框 架 。 


这 个 包 用 于 放置 生成 的 接口 和 实现 类 。 在 默认 的 生成 器 中 ， 属 
性 "enableSubPackages" 用 来 控制 如 何 计算 实际 的 包 。 如 果 是 tr 
果 表 的 catalog 和 schema 存 在 ， 就 将 他 们 作为 子 包 加 起 来 。 如 
targetPackage ， 果 "enableSubPackages" 是 false (默认 值 ) ， 计 算 的 package 将 
targetPackage 属 性 指定 的 值 。MBG 将 创建 所 需 的 生成 包 的 文人 
注 : 实现 类 的 包 可 以 通过 指定 下 面 会 提 到 的 可 选 的 
implementationPackage 属性 。 


这 用 来 指定 生成 接口 和 类 的 目标 项 目 。 当 在 Eclipse 环境 中 运行 | 
targetProject 项 指定 保存 对 象 的 位 置 的 项 目 和 源 文件 夹 。 在 其 他 环境 中 ， 此 1 
地 文件 系统 上 的 现 有 目录 。 如 果 它 不 存在 ，MBG 不 会 创建 它 。 


属性 描述 

如 果 指 定 了 该 属性 ， 实 现 类 就 会 生成 在 这 个 包 中 。 
在 默认 的 生成 器 中 ， 属 性 "enableSubPackages" 用 
来 控制 如 何 计 算 实 际 的 包 。 如 果 是 true， 如 果 表 的 

implementationPackage ， catalog 和 schema 存 在 ， 就 将 他 们 作为 子 包 加 起 
来 。 如 果 "enableSubPackages" 有 是 false (默认 
值 ) ， 计 算 的 package 将 是 targetPackage 属 性 指定 
的 值 。 MBG 将 创建 所 需 的 生成 包 的 文件 夹 。 


子 元 素 


e <property> (0..N) 


支持 的 属性 
这 个 表格 列 出 了 所 有 可 以 通过 <property> 子 元 素 进 行 设置 的 属性 : 


属性 名 属性 值 


这 个 属性 用 来 选择 MGB 是 否 根据 基于 目录 和 内 省 表 来 
Java 包 。 例 如 ， 假 设 菜 个 表 MYTABLE 在 MYSCHMAK 


enableSubPackages 


exampleMethodVisibility 


methodNameCalculator 


rootInterface 


useLegacyBuilder 


示例 


中 ， 也 假设 targetPackage 属 性 的 值 设 置 为 "com.myco 
果 此 属性 为 true， 为 这 个 表 生成 的 DAO 接 口 和 类 将 被 广 
包 "com.mycompany.myschema" 中 。 如 果 此 属性 是 fa 
SQL 映射 将 被 放 在 "com.mycompany" schema È ° 21 


此 属性 用 来 设置 不 同 "ByExample" 方 法 的 可 见 性 - 

selectByExample, deleteByExample 等 等 。 如 果 没 有 . 
方法 将 会 是 公开 的 的 ， 并 将 在 接口 中 声明 。 此 属性 使 
这 些 方法 如 果 您 只 想 使 用 它们 来 执行 其 他 专门 的 方法 ， 


public 这 是 默认 值 生成 实现 类 中 的 方法 将 是 公开 的 ，: 
声明 的 方法 。 


private 生成 实现 类 中 的 方法 将 是 private 的 ， 也 不 会 在 . 
明 。 


protected 生成 实现 类 中 的 方法 将 是 protected 的 ， 也 不 
声明 。 


default 生成 实现 类 中 的 方法 将 是 包 内 可 见 的 ， 也 不 会 . 
明 。 


重要 提示 : 如 果 目 标 运行 时 是 MyBatis3， 则 将 忽略 此 属 


此 属性 用 于 选择 一 个 方法 名 称 计 算 器 。 方法 名 称 计 算 
为 DAO 方 法 提供 不 同 的 名 称 。 您 可 以 选择 一 个 预定 义 
提供 的 选项 都 适合 您 的 环境 ， 也 可 以 指定 一 个 实现 
了 org.mybatis.generator.api.DAOMethodNameCa 
口 的 完全 限定 名 称 。 

default 这 是 默认 值 生成 的 方法 名 称 会 很 简单 ("insert", 
"UpdateByPrimaryKey" 等 等 )。 

extended 生成 的 方法 名 称 将 包括 与 方法 关联 的 实体 对 
("insertWidget", "updateWidgetByPrimaryKey" 等 等 )。 


重要 提示 : this property is ignored if the target runtime 
MyBatis3. 


此 属性 用 于 指定 一 个 所 有 生成 的 接口 都 继承 的 父 接口 ， 
以 通过 表 配 置 的 rootInterface BBA ° EŻ] 
接口 是 否 存在 或 者 是 否 是 一 个 有 效 的 接口 。 如 果 指 定 
应 该 是 一 个 全 限定 接口 名 称 (例如 
com.github.abel533.mapper.Mapper) ° 


to RA true > BAK P 344148 M SqlBuilder A MyBatis 4 
SQL ° 在 MyBatis 3.2 或 以 后 版 本 ， 这 个 SqlBuilder 废 ; 
个 新 的 SQL 类 替代 。 如 果 是 false，MBG 会 使 用 新 的 S 
成 客户 端 代码 。 默 认 值 是 false 


此 元 素 指 定 我 们 总 希望 生成 的 接口 和 对 象 在 "text.model' 包 中 ， 并 且 我 们 希望 使 用 基 
于 schema 和 catalog 的 子 包 。 它 还 指定 了 我 们 想 使 用 为 MyBatis3 的 XML 配置 文件 的 
mapper 接 口 。 


<javaClientGenerator targetPackage="test.model" 
targetProject="\MyProject\src" type="XMLMAPPER"> 
<property name="enableSubPackages" value="true" /> 
</javaClientGenerator> 


The <javaModelGenerator> Element 


The <javaModelGenerator> element is used to define properties of the Java 
model generator. The Java Model Generator builds primary key classes, record 
classes, and Query by Example classes that match the introspected table. This 
element is a required child element of the <context> element. 


必 选 属性 


属性 描述 


This is the package where the generated classes will be 
placed. In the default generator, the property 
"“enableSubPackages" controls how the actual package is 
calculated. If true, then the calculated package will be the 

targetPackage targetPackage plus sub packages for the table's catalog and 
schema if they exist. If false (the default) then the calculated 
package will be exactly what is specified in the 
targetPackage attribute. MyBatis Generator will create 
folders as required for the generated packages. 


This is used to specify a target project for the generated 
objects. When running in the Eclipse environment, this 
specifies the project and source folder where the objects will 
be saved. In other environments, this value should be an 
existing directory on the local file system. MyBatis Generator 
will not create this directory if it does not exist. 


targetProject 


可 选 属性 
无 


FAK 


e <property> (0..N) 
支持 的 属性 


下 面 的 表格 列 出 了 所 有 可 用 的 <property> 子 元 素 : 
属性 名 属性 值 


constructorBased 


enableSubPackages 


immutable 


rootClass 


This property is used to select whether MyBatis 
Generator will generate a constructor for the class that 
accepts a value for each field in the class. Also, the 
SQL result map will be built to use the constructor 
rather than the "setter for each field.This property is 
only applicable for MyBatis3 and will be ignored for 
iBATIS2.This property is ignored (and forced "true") if 
the "immutable" property is set "true". This property 
can be overridden by the corresponding property in a 
<table> element. 7144 Æ false 


This property is used to select whether MyBatis 
Generator will generate different Java packages for 
the objects based on the catalog and schema of the 
introspected table.For example, suppose a table 
MYTABLE in schema MYSCHMA. Also suppose that 
the targetPackage attribute is set to 
"com.mycompany". If this property is true, the 
generated objects for the table will be placed in the 
package "com.mycompany.myschema". If the property 
is false, the generated objects will be placed in the 
"com.mycompany" schema. 1 ii false 


This property is used to select whether MyBatis 
Generator will generate immutable model classes - 
this means that the classes will not have "setter" 
methods and the constructor will accept values for 
each field in the class. If true, this forces the model 
classes to be built with paramterized constructors 
regardless of the value of the "constructorBased" 
property. This property is only applicable for MyBatis3 
and will be ignored for iBATIS2.This property can be 
overridden by the corresponding property in a <table> 
element. RUME% false 


This property can be used to specify a root class for all 
generated Java model objects. MyBatis Generator will 
specify this value as the super class of the primary key 
object, if the table has a primary key, or the record 
object otherwise. This value may be overridden by 
specifying the rootClass property on a Table 
configuration. #: If MyBatis Generator is able to 
load the root class, then it will not override a property 
in the root class that exactly matches a property that 
would normally be generated. An exact match of a 
property is defined as follows 


Property name matches exactly 


Property is of the same type 


Property has a "getter method 
Property has a "setter" method 


If specified, the value of this property should be a fully 
qualified class name (like 
com.mycompany.MyRootClass). 


This property is used to select whether MyBatis 
Generator adds code to trim the white space from 
character fields returned from the database. This can 

trimStrings be useful if your database stores data in CHAR fields 
rather than VARCHAR fields. When true, MyBatis 
Generator will insert code to trim character fields. At 
值 是 false 


示例 


This element specifies that we always want to place generated classes in the 
“test.model" package and that we want to use subpackages based on the table 
schema and catalog. We also want String columns trimmed. 


<javaModelGenerator targetPackage="test.model" 
targetProject="\MyProject\src"> 
<property name="enableSubPackages" value="true" /> 
<property name="trimStrings" value="true" /> 
</javaModelGenerator> 


The <javaTypeResolver> Element 


The <javaTypeResolver> element is used to define properties of the Java Type 
Resolver. The Java Type Resolver is used to calculate Java types from database 
column information. The default Java Type Resolver attempts to make JDBC 
DECIMAL and NUMERIC types easier to use by substituting Integral types if 
possible (Long, Integer, Short, etc.) If this behavior is undesirable, set the property 
"forceBigDecimals" to "true". You can also substitute your own implementation if 
you want different behavior than the default. This element is an optional child 
element of the <context> element. 


必 选 属性 
z 
可 选 属性 
a 描述 


This can be used to specify a user provided Java Type Resolver. The 
class must implement the interface 

org.mybatis.generator.api.JavaTypeResolver ,必须 有 一 个 公开 
默认 的 构造 函数 。. The attribute also accepts the special value 
DEFAULT in which case the default implementation will be used (this 
has the same effect as not specifying the type). 


type 


FAK 


e <property> (0..N) 


支持 的 属性 


下 面 的 表格 列 出 了 所 有 可 用 的 <property> 子 元 素 : 


属性 名 属性 值 


This property is used to specify whether MyBatis 
Generator should force the use of 

forceBigDecimals java.math.BigDecimal for DECIMAL and NUMERIC 
fields, rather than substituting integral types when 
possible. 这 个 属性 有 以 下 可 选 值 : 


false 这 是 默认 值 当 这 个 属性 是 false 或 者 没有 指定 时 ，the 
default Java type resolver will attempt to make JDBC 
DECIMAL and NUMERIC types easier to work with by 
substituting Integral types if possible. The substitution 
rules are as follows: 


If the scale is greater then zero, or the length is greater 
than 18, then the java.math.BigDecimal type will be used 


If the scale is zero, and the length is 10 through 18, then 
the Java type resolver will substitute a java.lang.Long. 


If the scale is zero, and the length is 5 through 9, then the 
Java type resolver will substitute a java.lang.Integer. 


If the scale is zero, and the length is less than 5, then the 
Java type resolver will substitute a java.lang.Short. 


true 当 这 个 属性 是 true 时 ，the Java type resolver will 
always use java.math.BigDecimal if the database column 
is of type DECIMAL or NUMERIC. 


示例 


This element specifies that we always want to use the java.math.BigDecimal type 
for DECIMAL and NUMERIC columns: 


<javaTypeResolver> 
<property name="forceBigDecimals" value="true" /> 
</javaTypeResolver> 


<jdbcConnection> 元 素 


<jdbcConnection> 元 素 用 于 指定 数据 库 连接 所 需 的 内 省 表 的 属性 。 MyBatis 
Generator 使 用 JDBC 的 数据 库 元 数据 类 来 发 现 您 在 配置 中 指定 的 属性 表 。 每 一 个 
<context> 都 必须 有 一 个 <jdbcConnection> 元 素 。 


必 选 属性 
属性 描述 
driverClass 用 于 访问 数据 库 的 JDBC 驱 动 程序 的 完全 限定 类 名 称 。 


connectionURL 用 于 访问 数据 库 的 JDBC 连 接 URL ° 


可 选 属性 
属性 描述 
userld 访问 数据 库 的 用 户 ID © 
password 访问 数据 库 的 密码 。 
J 


e <property> (0..N) 注意 : 这 里 指定 的 任何 属性 将 添加 到 JDBC 了 驱动 程序 的 属性 
Po 


示例 


此 元 素 将 连接 到 DB2 数 据 库 配置 为 MBGTEST 在 DB2 客 户 端 配置 实用 程序 。 使 用 
JDBC 驱 动 程序 的 默认 安装 位 置 : 


<jdbcConnection driverClass="COM.ibm.db2.jdbc.app.DB2Driver" 
connectionURL="jdbc:db2:MBGTEST" 
userId="db2admin" 
password="db2admin"> 

</jdbcConnection> 
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<plugin> 元 素 


<plugin> 元 素 用 来 定义 一 个 插件 。 插 件 用 于 扩展 或 修改 通过 MyBatis Generator 
(MBG) 代 码 生 成 器 生成 的 代码 。 这 是 <context> 元 素 的 一 个 子 元 素 。 可 以 在 
context 指 定 任 意 数量 的 插件 。 插 件 将 在 配置 中 配置 的 顺序 执行 。 


有 关 执 行 插件 的 详细 信息 ， 请 参阅 Implementing Plugins 页 面 的 引用 。 


有 关 MyBatis Generator 提 供 的 插件 代码 生成 器 的 详细 信息 ， 请 参阅 Supplied 
Plugins 提 供 参 考 页 。 


必 选 属性 
e 描述 


实现 该 接口 的 类 的 完全 限定 名 的 插件 。 该 类 必须 实现 该 接口 
org.mybatis.generator.api.Plugin ,必须 有 一 个 公开 上 默认 的 构造 
Hao HB? AA org.mybatis.generator.api.PluginAdapter 这 
个 适配器 类 比 继承 接口 更 容易 扩展 。 


type 


可 选 属性 
无 


子 元 素 


e <property> (0 or 1) 


<properties> 元 素 


<properties> 元 素 用 于 指定 一 个 需要 在 配置 中 解析 使 用 的 外 部 属性 文件 。 属性 配置 
中 的 任何 属性 将 接受 ${property} 这 种 形式 的 属性 。 从 指定 的 属性 文件 中 搜索 
匹配 的 值 ， 配 置 的 值 将 会 被 蔡 换 。 属性 文件 时 正常 的 Java 属 性 文件 的 格式 。 


<properties> 元 素 是 <generatorConfiguration> 元 素 的 子 元 素 。 


必 选 属性 
以 下 属性 是 必需 的 ， 并 且 只 能 有 其 中 一 个 。 


属性 描述 
属性 文件 的 全 限定 名 称 。 当 指定 了 resource 必 性， 将 会 从 classpath 
下 面 搜索 属性 文件 。 当 指 定 为 
com/myproject/generatorConfig.properties 时 ， 他 必须 存 
在 com.myproject 包 下 面 。 


属性 文件 的 URL 值 。 这 可 以 用 于 指定 一 个 属性 文件 在 文件 系统 上 的 
url 特定 位 置 ， 例 如 
file:///C:/myfolder/generatorConfig.properties ° 


<property> 元 条 
<property> 元 素 用 于 指定 许多 其 他 元 素 的 属性 。 每 个 支持 属性 元 素 的 文档 页 面 列 出 


的 不 同 值 都 是 有 效 的 。 此 元 素 也 可 以 用 于 将 属性 传递 给 您 的 任何 自 定义 的 代码 生成 
器 执行 。 


必 选 属性 


属性 描述 
name 属性 的 名 称 ( 区 分 大 小 写 ) 。 
value 属性 的 值 (通常 是 不 区 分 大 小 写 ) 。 


<sqiMapGenerator> Z% 

<sqiMapGenerator> element 用 于 定义 SQL 了 映射 生成 器 的 属性 。 SQL 映射 生成 器 为 
每 一 个 内 省 的 表 生 成 MyBatis/iBATIS 形 式 的 XML 文件 。 

如 果 目 标 是 iBATIS2， 那 么 这 个 元 素 是 <context> 元 素 的 一 个 必须 的 子 元 素 。 


如 果 目 标 是 MyBatis3， 那 么 只 有 当 您 选择 javaClientGenerator 需 要 XML 时 ， 他 才 是 
<context> 元 素 的 一 个 必须 的 子 元 素 。 


如 果 不 指 是 一 个 javaClientGenerator， 则 适用 以 下 规则 : 


e 如 果 您 指定 一 个 sqlMapGenerator， 那 么 MBG 将 只 生成 SQL 了 映射 的 XML 文件 和 
模型 对 象 。 
© 如 果 您 没有 指定 一 个 sqlIMapGenerator， 那 么 MBG 将 只 会 生成 模型 对 象 。 


必 选 属性 


属性 描述 


这 个 包 用 于 放置 生成 的 SQL 了 映射 文件 。 在 默认 的 生成 器 中 ， 
属性 "enableSubPackages" 用 来 控制 如 何 计 算 实 际 的 包 。 如 
果 是 true， 如 果 表 的 catalog 和 Schema 存在， 就 将 他 们 作为 子 

9 包 加 起 来 。 如 果 "enableSubPackages" 是 false (上 默认 值 ) ， 
计算 的 package 将 是 targetPackage 属 性 指定 的 值 。MBG 将 
创建 所 需 的 生成 包 的 文件 夹 。 


这 用 来 指定 生成 SQL 映射 的 目标 项 目 。 当 在 Eclipse 环境 中 运 

targetProject 行 时 ， 此 选项 指 定 保存 对 象 的 位 置 的 项 目 和 源 文件 夹 。 在 其 
他 环境 中 ， 此 值 应 为 本 地 文件 系统 上 的 现 有 目录 。 如 果 它 不 
存在 ，MBG 不 会 创建 它 。 


可 选 属性 
无 


FAK 


e <property> (0..N) 


支持 的 属性 


下 面 的 表格 列 出 了 所 有 可 用 的 <property> 子 元 素 : 


属性 名 属性 值 


这 个 属性 用 来 选择 MGB 是 否 根 据 基 于 目录 和 内 省 表 来 
生成 不 同 的 Java 包 。 例 如 ， 假 设 某 个 表 MYTABLE 在 
MYSCHMA 的 Schema 中， 也 假设 targetPackage 属 性 的 
值 设置 为 "com.mycompany"。 如 果 此 属性 为 true， 为 
enableSubPackages 。 这 个 表 生 成 的 DAO 接 口 和 关 将 被 放置 在 
包 "com.mycompany.myschema" 中 。 如 果 此 属性 是 
false， 生 成 的 SQL 了 映射 将 被 放 在 "com.mycompany" 
schema ¥ ° RUIA false 


示例 


此 元 素 指定 我 们 总 希望 生成 的 SQL 映射 文件 在 "text.model' 包 中 ， 并 且 我 们 希望 使 用 
基于 schema 和 catalog 的 子 包 。 它 还 指定 了 我 们 想 使 用 为 MyBatis3 的 XML 配置 文件 
的 mapper 接 口 。 


<sqlMapGenerator targetPackage="test.model" 
targetProject="\MyProject\src"> 
<property name="enableSubPackages" value="true" /> 
</sqlMapGenerator> 


schema 


catalog 


alias 


domainObjectName 


enablelnsert 


enableSelectByPrimaryKey 


enableSelectByExample 


enableUpdateByPrimaryKey 


enableDeleteByPrimaryKey 


enableDeleteByExample 


enableCountByExample 


enableUpdateByExample 


selectByPrimaryKeyQueryld 


首 述 


数据 库 Schema - 如 果 您 的 数据 库 不 使 用 Schema ， 或 者 
有 一 个 默认 的 schema 您 不 需要 设置 schema。 如 果 需 
要 ， 指 定 的 值 可 以 包含 SQL 通配符 。 


数据 库 catalog - 如 果 您 的 数据 库 不 使 用 catalog， 或 者 有 
一 个 默认 的 catalog， 您 就 不 需要 设置 catalog。 


如 果 指 定 ， 这 个 值 会 用 在 生成 的 select 查询 SQL 的 表 的 别 
名 和 列 名 上 。 列 名 会 被 别名 为 


aliasactualColumnName( 别 名 实际 列 名 ) 这 种 模式 。 


生成 对 象 的 基本 名 称 。 如 果 没 有 指定 ，MBG 会 自动 根据 
表 名 来 生成 名 称 。 这 个 〈 指 定 或 者 自动 生成 的 ) 名 字 将 
用 于 计算 实体 类 的 名 称 和 DAO 类 的 名 称 。 您 可 以 在 实体 
对 象 的 名 字 上 指定 包 名 分 割 。 例如 ， 您 可 以 指 

定 foo,.Bar， 然 后 实体 对 象 的 名 字 会 是 Bar ， 包 名 foo 会 
添加 到 生成 器 配置 中 指定 的 目标 包 后 面 。 


指定 是 否 生 成 Insert 语 句 。 上 默认 值 是 true。 


指定 是 否 生 成 通过 主键 查询 的 语句 。 无 论 这 个 怎么 设 
置 ， 当 表 不 存在 主键 的 时 候 ， 不 会 生成 这 个 语句 。 默 认 
fai xe true ° 


指定 是 否 生 成 通过 Example 查 询 的 语句 。 这 个 语句 支持 
运行 时 生成 多 种 不 同 条 件 的 动态 查询 。 默 认 值 是 true。 


指定 是 否 生 成 通过 主键 更 新 的 语句 。 无 论 这 个 怎么 设 
， 当 表 不 存在 主键 的 时 候 ， 不 会 生成 这 个 语句 。 默 认 


除 的 语句 。 无 论 这 个 怎么 设 
置 ， Peers 不 会 生成 这 个 语句 。 默 认 
值 是 true ° 


指定 是 否 生 成 通过 Example 删 除 的 语句 。 这 个 语句 支持 
运行 时 生成 多 种 不 同 的 条 件 动态 删除 。 默 认 值 是 true。 


指定 是 否 生 成 通过 Example 查 询 总 数 的 语句 。 这 个 语句 
将 返回 满足 Example 条 件 的 数据 总 数 。 默 认 值 是 true。 


指定 是 否 生 成 通过 Example 更 新 的 语 抑 。 这 个 语句 将 更 
新 满足 Example 条 件 的 数据 。 如 果 设 置 为 
True,UpdateByExampleSelective 语 多 也 会 生成 。 这 个 语 
名 只 会 更 新 那些 参数 中 值 不 为 null 的 的 列 。 默 认 值 是 

true ° 


这 个 值 会 以 "<value>' as QUERYID" 这 种 形式 被 添加 到 通 
过 主键 查询 的 语句 的 select 列 中 。 这 可 能 对 在 运行 时 的 
DBA 跟 踪 工 具 中 标记 查询 有 用 。 如 果 您 使 用 这 个 值 ， 您 
需要 为 MBG 生 成 的 每 一 个 查询 指定 一 个 唯一 的 id © 





selectByExampleQueryld 


modelType 
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这 个 值 会 以 "<value>' as QUERYID" 这 种 形式 被 添加 到 通 
过 Example 查 询 的 语句 的 select 列 中 。 这 可 能 对 在 运行 时 
的 DBA 跟 踪 工 具 中 标记 查询 有 用 。 如 果 您 使 用 这 个 值 ， 
您 需要 为 MBG 生 成 的 每 一 个 查询 指定 一 个 唯一 的 id © 


如 果 您 需要 ， 这 个 值 可 以 用 来 重 写 默认 的 模型 类 型 。 如 

果 没 有 指定 ，MBG 将 会 生成 基于 上 下 文 默认 模型 类 型 的 

实体 对 象 。 模型 类 型 定义 了 MBG 如 何 生 成 实体 类 。 有 一 
些 模型 类 型 MGB 会 为 每 个 表 生 成 一 个 单独 的 实体 类 。 F 

外 一 些 模型 ，MGB 会 根据 表 结 构 生 成 不 同 的 一 些 类 。 这 
个 属性 有 以 下 可 选 值 : 


conditional 这 个 模型 和 hierarchical 类 似 ， 除 了 如 果 那 个 
单独 的 类 将 只 包含 一 个 字段 ， 将 不 会 生成 一 个 单独 的 

类 。 因此 ,如 果 一 个 表 的 主键 只 有 一 个 字段 ,那么 不 会 为 该 
字段 生成 单独 的 实体 类 ,会 将 该 字段 合并 到 基本 实体 类 
H 


flat 该 模型 为 每 一 张 表 只 生成 一 个 实体 类 。 这 个 实体 类 包 
含 表 中 的 所 有 字段 。 


hierarchical 如 果 表 有 主键 ,那么 该 模型 会 产生 一 个 单独 的 
主键 实体 类 ,如 果 表 还 有 BLOB 字 段 ， 则 会 为 表 生 成 一 个 
包含 所 有 BLOB 字 段 的 单独 的 实体 类 ,然后 为 所 有 其 他 的 
字段 生成 一 个 单独 的 实体 类 。 MBG 会 在 所 有 生成 的 实体 
类 之 间 维 护 一 个 继承 关系 ( 注 : BLOB 类 继承 其 他 字段 
类 继承 主键 类 ) © 


这 个 属性 表示 当 查 询 列 ， 是 和 否 对 Schema 和 表 名 中 的 SQL 
通配符 ("and '%') 进行 转 义 。 对 于 茶 些 驱动 当 schema 或 


escapeWildcards 表 名 中 包含 SQL 通 配 符 时 (例如 ， 一 个 表 名 是 


MY_TABLE， 有 一 些 驱 动 需要 将 下 划 线 进行 转 义 ) 是 必 
须 的 。 上 默认 值 是 _false. 


这 个 属性 表示 当 查 询 表 并 且 在 生成 的 SQL 中 分 隔 标识 符 
时 ， 是 否 使 用 指定 的 确切 的 值 。 有 关 更 多 详细 信息 ， 请 


delimitldentifiers 参见 上 面 的 详 述 。 分 隔 符 在 <context> 元 素 上 指定 。 默 


认 值 是 false。 除 非 catalog, schema 或 tableName # 
性 值 包 含 空白 时 ， 是 true. 


指示 是 否 给 生成 SQL 中 所 有 的 列 名 添加 分 隔 符 。 这 是 一 
种 给 每 个 列 添加 &1t;columnOverride&gt; 来 指定 列 需 要 


delimitAllColumns 被 分 隔 的 替代 方式 。 这 对 类 似 PostgreSQL 这 种 使 用 小 写 


标识 符 的 数据 库 很 有 用 。 分 隔 符 在 <context> 元 素 上 指 
定 。 默 认 值 是 false. 


FAR 


<property> (0..N) 
<generatedKey> (0 or 1) 
<columnRenamingRule> (0 or 1) 
<columnOverride> (0..N) 
<ignoreColumn> (0..N) 


支持 的 属性 


下 面 的 表格 列 出 了 所 有 可 用 的 <property> 子 元 素 : 


属性 名 


constructorBased 


ignoreQualifiersAtRuntime 


immutable 


modelOnly 


rootClass 


rootlnterface 


属性 值 


此 属性 用 于 选择 代码 生成 器 是 否 生成 接受 类 中 的 每 个 字 
段 的 值 的 类 的 构造 函数 。 此 外 ，SQL 结 果 映 射 也 会 为 
每 个 字段 生成 使 用 构造 方法 而 不 是 "setter" 的 方式 。 此 
属性 仅 适 用 于 MyBatis3 > iBATIS2 将 会 被 忽略 。 如 

果 "immutable" 属 性 设置 为 "true"， 这 个 属性 将 会 被 忽 
略 。 默 认 值 是 false 


如 果 设 置 为 rue，MBG 不 会 讲 Schema 或 catalog 添 加 到 
生成 SQL 中 的 表 名 上 。 如 果 您 有 几 个 schemas 中 的 表 
具有 相同 的 名 称 ， 这 是 非常 有 用 的 。 您 可 以 使 用 MBG 
生成 基于 在 一 个 schema 上 的 表 ， 但 是 运行 时 不 包含 
schema。 默 认 值 是 false 


此 属性 用 于 选择 MBG 是 否 会 生成 不 可 变 的 模型 类 。 这 
意味 着 这 些 类 不 会 包含 "setter" 方 法 ， 而 且 通 过 构造 参 

数 接收 类 中 所 有 字段 的 值 。 如 果 设 置 为 true, 将 会 忽 

略 "constructorBased" 属 性 ， 强 制 生成 通过 参数 化 构造 
方法 的 模型 类 。 此 属性 仅 适 用 于 MyBatis3，iBATIS2 将 
会 被 忽略 。 默 认 值 是 false 


此 属性 用 于 选择 MBG 是 否 只 会 为 表 生 成 模型 类 。 如 果 
设置 为 true， 那 么 就 不 会 生成 Java 客 户 端 类 。 如 果 
<sqlMapGenerator> 配置 了 ， 并 且 属 性 设置 为 true， 那 
么 MGB 将 会 在 该 表 的 SQL 映射 XML 中 只 生成 结果 映射 
元 素 。 如 果 设 置 为 true， 这 个 值 会 覆盖 <table> 元 素 上 
所 有 的 "enable*" 属 性 ， 将 不 会 生成 任何 CRUD 方 法 。 默 
认 值 是 false 


这 个 属性 可 以 用 来 指定 所 有 生成 的 Java 模 型 类 的 基 

类 。 如 果 表 包含 主键 ，MBG 会 将 该 值 指定 为 主键 对 象 

的 超 类 。 或 者 其 他 记录 对 象 的 超 类 。 这 个 值 将 会 覆盖 

Java 模 型 生成 配置 中 配置 的 rootClass 重 要 : 如 果 MBG 
可 以 加 载 基 类 ， 通 常生 成 的 属性 不 会 履 盖 和 基 类 中 完全 
匹配 的 属性 。 完全 匹配 属性 的 定义 如 下 


属性 名 称 完全 相同 

属性 的 类 型 相同 

属性 有 一 个 "getter" 方 法 
属性 有 一 个 "setter" 方 法 


如 果 指 定 这 个 值 ， 这 个 属性 值 应 该 是 一 个 完全 限定 的 类 
名 (例如 : com.mycompany.MyRootClass). 


这 个 属性 可 以 用 来 指定 所 有 生成 的 DAO 接 口 对 象 的 父 
接口 。 这 个 属性 值 会 覆盖 DAO 生 成 器 配置 中 配置 

的 rootInterface 属 性 。 重 要 : MBG 不 会 校 验 接 口 是 
否 存 在 或 者 合法 。 如 果 指 定 这 个 值 ， 这 个 属性 值 应 该 是 


runtimeCatalog 


runtimeSchema 


runtime TableName 


selectAllOrderByClause 


useActualColumnNames 


useColumnIndexes 


useCompoundPropertyNames 


示例 


一 个 完全 限定 的 接口 名 (例如 : 
com.mycompany.MyRootlnterface). 

如 果 您 指定 了 这 个 属性 值 ，MBG 会 在 生成 的 SQL 中 使 
用 这 个 catalog， 而 不 是 前 面 配置 的 catalog 属性 值 。 
当 您 生成 代码 的 catalog 和 运行 时 的 catalog 不 一 样 时 ， 
这 会 非常 有 用 。 

如 果 您 指定 了 这 个 属性 值 ，MBG 会 在 生成 的 SQL 中 使 
用 这 个 schema， 而 不 是 前 面 配置 的 schema 属性 值 。 
当 您 生成 代码 的 Schema 和 运行 时 的 Schema 不 一 样 时 ， 
这 会 非常 有 用 。 


如 果 您 指定 了 这 个 属性 值 ，MBG 会 在 生成 的 SQL 中 使 
用 这 个 表 名 ， 而 不 是 前 面 配 置 的 tableName 属性 值 。 
当 您 想 在 Oracle 中 使 用 公共 同义词 生成 对 象 时 ， 这 会 非 
常 有 用 。 在 这 种 情况 下 ， 您 将 需要 生成 对 象 的 同义词 
的 指向 您 实际 表 。 那 就 在 此 属性 中 指定 同义词 名 称 。 
在 使 用 公共 同义词 的 大 多 数 情况 下 ， 您 还 需要 设置 
ignoreQualifiersAtRuntime 属 性 。 


这 个 属性 可 以 用 于 指定 将 会 加 到 selectAll 方法 中 的 
order by 语句 。 这 仅 适 用 于 您 使 用 MyBatis3Simple 目 
标 运 行 环境 时 。 MBG 会 将 您 在 这 儿 指 定 的 任何 属性 值 
前 面 追加 order by ， 因 此 该 属性 启 仅 包含 列表 中 的 列 
(例如 ID1, ID2 或 ID1 desc, ID2 asc) 


如 果 设 置 为 true, 那 么 MBG 会 使 用 从 数据 库 元 数据 获取 
的 列 名 作为 生成 的 实体 对 象 的 属性 。 如果 为 false( 默 认 
值 )，MGB 将 会 尝试 将 返回 的 名 称 转换 为 驼峰 有 形式。 在 
这 两 种 情况 下 ， 可 以 通过 <columnOverride> 元 素 显 示 
指定 ， 在 这 种 情况 下 将 会 忽略 这 个 
(useActualColumnNames) 属性 。 例 如 ， 假 设 一 个 表 
包含 STARTDATE 列 ， 如 果 这 个 属性 是 %ue"” 那么 
MBG 生 成 的 属性 名 是 START_DATE - 这 意味 着 这 个 值 的 
getter 和 setter 方 法 将 会 是 getSTART_DATE() 和 
setSTART_DATE(). 如 果 这 个 属性 值 是 fasle,MBG 将 会 
生成 的 属性 名 是 startDate - 这 意味 着 这 个 值 的 getter 
和 sette/ 方 法 将 会 是 getStartDate() 和 
setStartDate(). 默 认 值 是 false _ 


如 果 是 true,MBG 生 成 resultMaps 的 时 候 会 使 用 列 的 索 
引 ,而 不 是 结果 中 列 名 的 顺序 . 当 表 中 的 列 名 的 区 别 只 是 
大 小 写 的 时 候 , 这 会 非常 有 用 . 这 个 支持 还 会 有 一 个 轻微 
的 性 能 优势 .默认 值 是 false 重 要 提示 : 当 目 标 运行 环境 
是 Mybatis 版 本 3 时 不 支持 这 个 属性 . 


如 果 是 true, 那 么 MBG 生 成 属性 名 的 时 候 会 将 列 名 和 列 
备注 接 起 来 . 这 对 于 那些 通过 第 四 代 语 言 自动 生成 列 ( 例 
如 :FLD22237), 但 是 备注 包含 有 用 信息 (例如 :"customer 
id") 的 数据 库 来 说 很 有 用 . 在 这 种 情况 下 ,MBG 会 生成 属 
性 名 FLD2237Customerld. 默 认 值 是 false_ 


这 个 元 素 指 定 我 们 总 是 想 为 一 个 在 MYSCHEMA schema 上 的 叫做 MYTABLE 的 表 
生成 代码 . 我 们 还 想 忽略 表 中 一 个 叫 "fred" 的 列 ,而 且 我 想 还 想 重 写 "BEG_DATA" 列 ， 
以 便 生 成 的 属性 名 是 "startDate". 


<table tableName="MYTABLE" schema="MYSCHEMA"> 
<ignoreColumn column="fred"/> 
<columnOverride column="BEG_DATE" property="startDate"/> 
</table> 


使 用 生成 的 对 象 


MyBatis Generator (MBG) 生成 这 些 类 型 的 对 象 : 


1. Java 模 型 对 象 (通常 ) 

2. SQL 映射 文件 (iBATIS 通 常 有 , MyBatis 经 常 有 ) 

3. SQL 映射 文件 (可 选 的 ) 

4. 一 个 在 xxxByExample 方 法 中 使 用 的 类 。 有 关 这 些 类 的 信息 ， 请 参阅 下 列 网 

页 : 
o Example 类 用 法 说 明 
o 扩展 Example 类 


这 些 独 立 的 页 面 有 这 些 对 象 的 说 明和 用 法 。 


JAVA 实体 对 象 


MyBatis Generator (MBG) 根 据 数 据 库 表 字 段 生 成 Java 类 . MBG 生 成 的 是 简单 实体 
对 象 而 非 带 业务 逮 辑 的 实体 对 象 ( 详 见 设计 理念 介绍 ).MBG 根 据 表 特 性 和 配置 生成 不 
同类 型 的 实体 对 象 . 

MBG 生 成 字段 和 方法 时 包含 JavaDoc 标 签 @mbggenerated .运行 Eclipse 插件 

时 ,MBG 会 将 每 个 Java 对 象 中 的 JavaDoc 标 签 删除 或 替换 .其 他 地 方 不 会 发 生变 化 . 在 
这 种 情况 下 ,您 在 Java 类 中 添加 的 字段 和 方法 就 不 用 担心 丢失 -- 不 包括 包含 了 
JavaDoc @mbggenerated 标签 部 分 内 容 . 


离开 Eclipse 插件 ， 您 需要 手动 合并 Java 文 件 ,但 是 使 用 JavaDoc 
的 @mbggenerated 标签 用 来 了 解 删除 以 前 版 本 的 文件 是 否 安全 . 


以 下 描述 生成 不 同 的 实体 对 象 .MBG 根 据 <context> 的 defaultModelType 属性 ( 支 
持 conditional、flat、hierarchical 三 个 值 ) 和 <table> 的 modelType (此 属性 用 于 履 盖 
默认 的 defaultModelType) 属 性 配置 生成 不 同 的 实体 对 象 . 


任何 字段 配置 了 <ignoreColumn>, 自 动 生 成 时 不 会 添加 到 Java 对 象 中 . 


注意 : 下 面 描述 中 "BLOB" 指 任何 列 的 BLOB 数 据 类 型 包括 BLOB, CLOB, 
LONGVARCHAR, 和 LONGVARBINARY. 


主键 类 


主键 类 在 表 中 包含 一 个 主键 的 字段 属性 . (MBG) 根 据 表 列 明 自动 生成 属性 名 称 .自动 
生成 的 属性 名 称 可 以 配置 &lt;columnOverride&gt; BERS. 


类 名 默认 情况 是 ?TableName?Key ,如 果 &lt;table&gt; 配置 
了 domainobjectName 属性 那么 类 名 是 ?domainobjectName?Key . 


如 果 表 中 存在 一 个 字段 的 主键 将 会 生成 hierarchical 类 型 实体 对 象 . 如 果 表 中 存在 多 
列 组 合 主键 将 会 生成 conditional 类 型 实体 对 象 .主键 类 是 不 会 生成 flat 类 型 实体 对 象 
model. 


ER 


主键 类 在 表 中 不 包含 主键 、BLOB 的 字段 属性 . 如 果 只 有 一 个 主键 记录 类 将 继承 主键 
类 . (MBG) 根 据 表 列 明 自 动 生成 属性 名 称 .自动 生成 的 属性 名 称 可 以 配 
置 &lt;columnOverride&gt; MER &. 


类 名 默认 情况 是 ?TableName? ,如 果 &lt;table&gt; 配置 
了 domainobjectName 属性 那么 类 名 是 ?domainobjectName? 配置 的 值 . 


如 果 表 中 不 存在 组 合 主键 、BLOB 列 将 生成 hierarchical 类 型 实体 对 象 .如 果 表 中 不 存 
一 个 字段 的 主键 、BLOB 列 或 只 有 一 个 主键 或 者 一 个 BLOB 列 将 生成 conditional 类 型 
实体 对 象 .记录 类 常常 生成 flat 类 型 实体 对 象 . 


BLOB 了 ?记录 关 


BLOB 记 录 类 在 表 中 包含 BLOB 字 段 属性 . 如 果 表 中 只 存在 一 个 字段 该 类 将 继承 基础 
类 , 或 将 继承 主键 类 (注意 :MBG 不 支持 表 中 只 包含 BLBO 列 ), (MBG) 根 据 表 列 明 自 动 
生成 属性 名 称 .自动 生成 的 属性 名 称 可 以 配置 &1lt;columnOverrideagt; AER &. 


BLOB 记 录 类 调用 selectByPrimaryKey 或 selectByExamplewithBLOBs 方法 返 
回 BLOB 字 段 值 . 


类 名 默认 情况 是 ?TableName?WithBLOBs ,如 果 &lt;table&gt; 配置 
了 domainobjectName 属性 那么 类 名 是 ?domainobjectName?WithBLOBS . 


如 果 表 中 存在 一 个 BLOB 列 将 生成 hierarchical 类 型 实体 对 象 . 如 果 表 中 存在 多 个 
BLOB 列 将 生成 conditional 类 型 实体 对 象 .BLOB 记 录 类 是 不 会 生成 flat 类 型 实体 对 象 . 


Example # 


Example 类 用 来 处 理 MBG 动 态 查 询 功 能 . Example R1% E AH A TA AWHERE F 4) 
下 列 方法 中 : 


selectByExample 
selectByExampleWithBLOBs 
deleteByExample 
countByExample 
updateByExample 


Example 类 不 继承 任何 实体 对 象 . 


类 名 默认 情况 是 ?TableName?Example ,如 果 &lt;tableagt; 配置 

了 domainobjectName 属性 那么 类 名 是 ?domainobjectName?Example . 

如 果 方 法 被 启动 Example 类 将 生成 任何 *ByExample 方法 .注意 :如 果 表 中 有 非常 多 
的 字段 该 类 可 能 很 大 ,但 DAO 生 成 的 XML 是 比较 小 的 . 如 果 您 不 需要 使 用 动态 
WHERE 子 句 , 您 可 以 禁用 生成 这 些 方 法 . 


详 见 Example 类 使 用 说 明了 解 详情 . 


SQL 了 映射 文件 


MyBatis Generator (MBG) 生 成 SQL 映射 文件 遵循 MyBatis 或 iBATIS SQL Map DTD 
规范 . 在 表 的 基础 上 这 些 文件 还 包含 了 不 同 的 标签 和 属性 配置 . MBG 按 照 配置 表 生 成 
SQL 映射 文件 . 表 名 就 是 SQL 了 映射 文件 的 命名 空间 (前 提 是 数据 库 支 持 Schema 和 
catalog, 主 流 数据 库 对 schema 和 catalog 都 支持 ).MBG 不 会 自动 把 SQL 了 映射 文件 到 
MyBatis/iBATIS 配 置 文件 中 - 您 必须 手动 把 xxxMapper.xml 文件 加 入 到 配置 文件 
中 (或 者 您 使 用 一 个 插件 使 MBG 生 成 配置 文件 ;Spring 配 置 文件 可 以 实现 自动 扫 

描 xxxMapper.xml 和 接口 ). 


每 个 自动 生成 的 XML 方 法 标签 下 都 包含 @mbggenerated 的 注释 块 .在 运行 的 时 

4& @mbggenerated 注释 块 将 删除 和 替换 .其 他 部 分 内 容 将 保持 不 变 . 考虑 到 这 点 ,不 
用 担心 在 运行 时 丢失 您 新 增 内 容 -- 不 包括 @mbggenerated 块 内 容 . 

以 下 部 分 描述 了 将 要 生成 的 元 素 . 


注意 :下 面 描述 中 "BLOB" 指 任何 列 的 BLOB 数 据 类 型 包括 BLOB, CLOB, 
LONGVARCHAR, 和 LONGVARBINARY. 


结果 集 


结果 集 用 于 数据 库 表 列 映射 Java 对 象 的 属性 . 结果 集 (和 相应 的 查询 语句 ) 不 包括 如 下 
情况 : 

e 任何 列 配置 &lt;ignoreCcolumn&gt; 属性 将 被 会 被 忽略 

。 任 何 BLOB 字 上 段 ( 详 见 有 关 BLOBs 字 段 相 关 映 射 ) 


对 于 列 配置 &lt;columnOverride&gt; 属性 将 映射 成 配置 的 名 称 .没有 配置 使 用 的 
是 默认 的 属性 和 JDBC 类 型 . 


对 于 自 定义 连接 查询 结果 集 继承 一 个 结果 集 是 一 种 非常 常见 的 用 法 . 对 于 其 他 连接 
查询 也 想 使 用 该 结果 集 在 MBG 自 动 生成 的 时 候 需 要 配置 前 级 . 详 见 <table> 属 性 alias 
配置 前 级 ,这 样 做 法 可 以 区 分 表 中 相同 字段 . 


如 采 table 配 置 enableSelectByExample、enableSelectByPrimaryKey 属 性 为 
true,MBG 会 生成 结果 集 ,table 默 认 这 两 个 配置 都 是 true, 所 以 大 部 分 情况 下 都 会 生成 
resultMap. 


BLOB 结 果 集 


表 中 存在 BLOB 字 段 时 MBG 会 自动 生成 一 个 BLOB 结 果 集 ,BLOB 结 果 集 继承 了 除 
BLOB 字 段 外 的 基础 结果 集 . 我 们 提供 不 同 的 版 本 查询 语句 ,来 适应 查询 结果 中 是 否 
需要 BLOB 字 段 . 


BLOB 结 果 集 ( 和 相应 的 查询 语句 ) 不 包括 如 下 情况 : 


e 任何 列 配置 &lt;ignoreColumn&gt; 属性 将 被 会 被 忽略 


对 于 列 配置 &lt;columnOverride&gt; 属性 将 映射 成 配置 的 名 称 .没有 配置 使 用 的 
是 默认 的 属性 和 JDBC 类 型 . 


对 于 自 定义 连接 查询 结果 集 继承 一 个 结果 集 是 一 种 非常 常见 的 用 法 .对 于 其 他 连接 查 
询 也 想 使 用 该 结果 集 , 在 MBG 自 动 生 成 的 时 候 需 要 配置 前 缓 . 详 见 <table> 性 alias 配 
置 前 级 ,这 样 做 法 可 以 区 分 表 中 相同 字段 . 


如 果 table 存 在 BLOB 字 段 且 配置 了 enableSelectByExample 、 
enableSelectByRrimaryKey 属 ， 性 ,MBG 会 生成 BLOB 结 果 集 ,table 默 认 这 两 个 配置 都 
是 true 所 以 大 部 分 情 况 下 都 会 生成 resultMap. 


Where & #+SQL 4) 


"by example" 方 法 重用 Where 条 件 .被 重用 的 Where 条 件 不 包括 BLOB 字 段 .大 部 分 表 
WHERE 条 件 都 不 支持 BLOB 字 上段 . 


"by example" 语 和 句 被 配置 将 动态 生成 Where 条 件 语句 . 


根据 主键 查询 


select 语 名 按照 主键 查询 返回 一 行 数据 .如 果 表 中 存在 BLOB 字 段 ,查询 结果 中 会 包 人 多 
该 字段 . 


oy 


如 果 table 配 置 了 nal od Ea enableSelectByPrimaryKey &' 性 为 
true,MBG 会 生成 结果 集 ,table 默 认 这 两 个 配置 都 是 true 所 以 大 部 分 情况 下 都 会 生成 
resultMap. 


根据 条 件 查 询 


根据 条 件 查 询 结果 集 和 自动 生成 对 象 相 匹 配 . 通过 实现 一 个 简单 的 "query by 
example" 方 法 可 以 适用 于 不 同 的 数据 库 查询 .就 算 表 中 存在 BLOB 字 段 该 查询 结果 集 
也 不 会 返回 该 BLOB 字 段 (具体 返回 BLOB 字 段 详 见 根据 条 件 查询 包含 BLOB 字 上 段 结 

果 集 部 分 描述 ) 


重要 :条 件 为 空 或 者 没有 设置 条 件 时 ,会 将 表 中 所 有 数据 查询 出 来 . 
如 果 table 配 置 了 enableSelectByExample 属 性 为 true,MBG 会 生成 Example 查 询 . 


根据 条 件 查 询 包 含 BLOB 字 上段 ( 方 
法 :selectByExampleWithBLOBs) 


Example 查 询 结果 集 和 自动 生成 对 象 相 匹配 . 通过 实现 一 个 简单 的 "query by 
example A T 以 适用 于 不 同 的 数据 库 查 询 . 算 表 中 存在 BLOB 字 段 该 查询 结果 集 将 
返回 该 BLOB 字 上 段 . 


重要 : 查询 条 件 为 空 或 者 没有 设置 查询 条 件 时 ,会 将 表 中 所 有 数据 查询 出 来 . 


如 果 table 配 置 了 enableSelectByExample 届 性 为 true,MBG 会 生成 包含 BLOB 字 上 段 的 
Example 查 询 . 


插入 
该 方法 可 以 插入 表 中 所 有 字段 (包括 BLOB 字 段 ), 但 列 配置 
了 &lt;ignoreColumn&gt; 属性 将 不 会 插入 ， 


如 果 表 有 主键 自动 增长 (自动 增长 列 或 序列 ) table 子 元 素 配 
置 &lt;generatedKey&gt; 属性 ,MBG 会 生成 &1lt;selectkKey&gt; 块 语句 ,一 般 
情 况 下 都 不 需要 配置 使 用 数据 库 自动 增长 即 可 , 除 非 表 字段 需 要 使 用 序列 . 


重要 提示 :与 BATIS2 和 MyBatis3 插 入 的 差异 .差异 如 下 
运行 特性 


置 了 <generatedKey> 属 性 ,插入 的 时 候 会 返回 新 的 自动 增长 值 . 没 
置 <generatedKey> 属 性 , 插入 返回 值 为 void . 


插入 方法 将 返回 插入 受 影 响 的 行 数 (通常 是 0 或 者 1). 林 
<generatedKey> 属 性 ,自动 增长 值 会 被 设置 在 e 


iBATIS2 
MyBatis3 


如 果 table 配 置 了 enablelnsert 属 性 为 true,MBG 会 生成 该 方法 . 


选择 性 插入 


该 方法 可 以 插入 表 中 所 有 字段 (包括 BLOB 字 段 ), 但 列 配置 

了 &lt;ignoreColumn&gt; 属性 将 不 会 插入 .然而 ,参数 对 象 AE 的 列 将 不 会 插入 
值 . 如 果 数据 库 列 eT RUA sae 否则 列 值 是 空 . 对 于 列 不 允许 为 = 情 
况 - 则 需要 人 为 确保 调用 该 方法 时 不 为 E IARA 值 使 插入 不 报错 .重要 :任何 映射 到 
java 引 用 类 型 的 字段 都 会 被 该 方法 插入 . 


如 果 表 有 主键 自动 增长 (自动 增长 列 或 序列 ),table 子 元 素 配 
置 &lt;generatedKey&gt; 属性 ,MBG 会 生成 &lt;selectKey&gt; 块 语句 ,一 般 
情况 下 都 不 需要 配置 使 用 数据 库 自动 增长 即 可 ,除非 表 字 段 需 要 使 用 序列 . 


重要 提示 :与 iBATIS2 和 MyBatis3 插 入 的 差异 .差异 如 下 


运行 特性 


置 了 <generatedKey> 属 性 ,插入 的 时 候 会 返回 新 的 自动 增长 值 . 没 
cet 没有 配 置 <generatedKey> 属性 , 插入 返回 值 为 void . 


插入 方法 将 返回 插入 受 影响 的 行 数 (通常 是 0 或 者 1). | 配置 = 
<generatedKey> 属 性 ,自动 增长 值 会 被 设置 在 参数 对 象 中 返 


iBATIS2 
MyBatis3 


如 果 table 配 置 了 enablelnsert 属 性 为 true,MBG 会 生成 该 方法 . 


根据 主键 更 新 


该 方法 按照 主键 修改 一 行 数据 .该 方法 会 修改 表 中 所 有 字段 ,除非 : 


e 列 配置 了 &lt;ignoreColumn&gt; 属性 
e。BLOB 字 上 段 ( 详 见 根据 主键 更 新 包含 BLOB 字 段 ) 


数据 库 表 中 存在 主键 且 table 配 置 了 enableUpdateByPrimaryKey 属 性 为 true,MBG 会 
生成 该 方法 . 


根据 主键 更 新 包含 BLOB 了 字段 


该 方法 按照 主键 修改 一 行 数据 .该 方法 会 修改 表 中 所 有 字段 (包括 BLOB 字 段 ), 除 非 : 
e 列 配置 了 &lt;ignoreColumn&gt; 属性 


数据 库 表 中 存在 主键 包含 BLOB 列 且 table 配 置 了 enableUpdateByPrimaryKey 属 性 为 
true MBG Rk 


根据 主键 选择 性 更 新 


该 方法 按照 主键 修改 一 行 数据 .该 方法 会 更 新 表 中 参数 对 象 属性 不 为 空 的 列 .该 方法 
可 以 被 使 用 更 新 某 些 特定 的 列 而 不 影响 所 有 列 数 据 . 重要 : 任何 映射 到 java 引 用 类 型 
的 字段 都 会 被 该 方法 更 新 . 


数据 库 表 中 存在 主键 且 table 配 置 了 enableUpdateByPrimaryKey 属 性 为 true,MBG 会 
生成 该 方法 . 


根据 主键 删除 记录 


该 方法 按照 主键 删除 一 行 数据 . 


数据 库 表 中 存在 主键 且 table 配 置 了 enableDeleteByPrimaryKey 属 性 为 true,MBG 会 
生成 该 方法 . 


根据 条 件 删除 记录 

该 方法 按照 条 件 将 删除 一 行 或 者 多 行 数据 . 

重要 :条 件 为 空 或 者 没有 设置 条 件 时 , 会 将 表 中 所 有 记录 删除 . 

如 果 table 配 置 了 enableDeleteByExample 属 性 为 true,MBG 会 生成 该 方法 . 


根据 条 件 查 询 记 录 总 类 


该 方法 按照 条 件 查 询 表 中 符合 条 件 记录 的 记录 总 数 . 
重要 :条 件 为 空 或 者 没有 设置 条 件 时 ,返回 表 中 所 有 记录 总 数 . 
如 果 table 配 置 了 enableCountByExample 属 性 为 true,MBG 会 生成 该 方法 . 


根据 条 件 更 新 记录 


该 方法 按照 条 件 更 新 表 中 符合 条 件 记 录 . 该 方法 会 修改 表 中 所 有 字段 ,除非 : 


e 列 配置 了 &lt;ignoreColumn&gt; 属性 
。BLOB 字 段 ( 详 见 根据 条 件 修改 记录 包 BLOB FFE) 


重要 :条 件 为 空 或 者 没有 设置 条 件 时 , 会 将 表 中 所 有 记录 更 新 . 
如 果 table 配 置 了 enableUpdateByExample 属 性 为 true,MBG 会 生成 该 方法 . 


根据 条 件 修 改 记 录 包 含 BLOB 字 段 


该 方法 按照 条 件 更 新 表 中 符合 条 件 记 录 . 该 方法 会 修改 表 中 所 有 字段 (包括 BLOB 字 
段 ), 除 非 : 

e 列 配 置 了 &lt;ignoreColumn&gt; 属性 
重要 :条 件 为 空 或 者 没有 设置 条 件 时 , 会 将 表 中 所 有 记录 更 新 . 


如 果 表 存在 BLOB 字 段 且 table 配 置 了 enableUpdateByExample 属 性 为 true,MBG 会 生 
成 该 方法 . 


根据 条 件 选 择 性 更 新 记录 


该 方法 按照 条 件 更 新 表 中 符合 条 件 记 录 . 该 方法 会 更 新 表 中 参数 对 象 属性 不 为 空 的 
列 . 该 方法 可 以 被 使 用 更 新 某 些 特定 的 列 而 不 影响 所 有 列 数据 .重要 : 任何 映射 到 java 
引用 类 型 的 字段 都 会 被 该 方法 更 新 . 


重要 :条 件 为 空 或 者 没有 设置 条 件 时 , 会 将 表 中 所 有 记录 更 新 . 


如 果 table 配 置 了 enableUpdateByExample 属 性 为 true,MBG 会 生成 该 方法 . 


Java 窜 户 端 对 象 


MyBatis Generator (MBG) 生 成 几 种 类 型 的 Java 客 户 端 对 象 .用 Java 的 客户 端 对 象 与 
所 产生 的 XML 交互 容易 得 多 . 对 于 配置 中 的 每 个 表 ，MBG 生 成 一 个 或 多 个 Java 客 户 
端 对 象 .如 MyBatis 的 3, 这 些 都 接口 映射 .对 于 iBATIS 的 2.x 中 ， 这 些 都 是 DAO 接 口 和 
实现 类 . 生成 Java 客 户 对 象 是 可 选 的 ,由 alt;javaClientGeneratoragt; 配置 . 
MBGr 可 以 产生 以 下 的 Java 客 户 短 对 象 类 型 : 


e 如 MyBatis 3.x: 

o XMLMAPPER - 用 与 支持 MyBatis 3.x 映 身 
e 如 iBATIS 2.x: 
IBATIS - 使 用 iBATIS DAO 框 架 
o SPRING - 与 Spring 框架 联合 使 用 
o GENERIC-CI - 使 用 不 依赖 iBATIS 数 据 映 射 
o GENERIC-SI - 使 用 不 依赖 iBATIS 数 据 映 射 


每 个 字段 和 方法 产生 包括 JavaDoc 标 签 @mbggenerated .Eclipse 插件 运行 时 , 运行 
中 每 个 字段 和 方法 包括 此 Javadoc 标 记 将 被 删除 并 替换 .在 类 中 的 其 他 任何 字段 或 方 
法 将 保持 不 变 . 考虑 到 这 一 点 ,您 可 以 不 用 担心 加 入 的 字段 和 方法 丢失 -不 包括 在 
Javadoc 标 签 @mbggenerated PA. 


离开 Eclipse 插件 ,您 需要 手动 合并 Java 文 件 ,但 是 使 用 JavaDoc 的 
@mbggenerated 标签 用 来 了 解 删除 以 前 版 本 的 文件 是 否 安全 . 


注意 : 下 面 描述 中 "BLOB" 指 任何 列 的 BLOB 数 据 类 型 包括 BLOB, CLOB, 
LONGVARCHAR, 和 LONGVARBINARY. 


(0) 


通用 DAO 方 法 
根据 表 的 特性 ,以 及 配置 选项 ,Java 客 户 端 自动 生成 如 下 方法 : 


countByExample 

deleteByPrimaryKey 

deleteByExample 

insert 

insertSelective 

selectByPrimaryKey 

selectByExample 

selectByExampleWithBLOBs 

updateByPrimaryKey ( 知 更 新 BLOB 字 段 需 要 重 写 方法 ) 
updateByPrimaryKeySelective (只 更 新 参数 类 非 空 字段 ) 
updateByExample ( 否 更 新 BLOB 字 段 需 要 重 写 方法 ) 
updateByExampleSelective (只 更 新 参数 类 非 空 字段 ) 


对 于 包含 BLOB 的 表 ,MBG 通 过 生成 不 同 的 对 象 和 方法 使 您 更 容易 使 用 BLOB 字 段 ,是 
和 否 忽略 它们 ,这 取决 于 具体 情况 . 


详 见 Example 类 使 用 说 明 中 selectByExample 方法 使 用 . 


XMLMAPPER 客户 端 (MyBatis 3.x) 


XMLMAPPER 客 户 端 是 将 接口 方法 映射 到 生成 的 XML 了 映射 文件 中 .例如 ,MBG 自 动 生 
成 的 接口 名 为 MyTableMapper .您 可 以 如 下 使 用 该 接口 : 


SqlSession sqlSession = sqlSessionFactory.openSession(); 


try { 
MyTableMapper mapper = sqlSession.getMapper (MyTableMapper .cl 
ass); 
List<MyTable> allRecords = mapper.selectByExample(null); 
} finally { 
sqlSession.close(); 
} 


有 关 如 何 创 建 实例 的 详细 信息 ,请 参阅 MyBatis 文 档 怎 么 创 
建 sqlSessionFactory 实例 . 


IBATIS DAOs (iBATIS 2.x) 


iBATIS DAO 依 赖 于 iBATIS 的 DAO 框 架 (iBATIS 的 一 个 可 选 部 分 - 现在 已 经 过 时 ). 他 
们 继承 SqIMapDaoTemplate 类 和 初始 化 DAOManager 对 象 的 实例 ,并 且 调 用 方法 执 
行 不同 的 语句 . 


MBG 不 会 为 您 更 新 "dao.xml" 文 件 - 您 必须 添加 手动 相应 的 内 容 . 
iBATIS DAO 框 架 是 一 个 非常 基础 的 loC 容 器 ,如 果 您 尚未 使 用 像 Spring 或 


PicoContainer 的 管理 依赖 关系 的 框架 ,ijBATIS DAO 框 架 可 能 会 有 用 . 然而 ,该 框架 现 
在 已 经 过 时 ,我 们 建议 您 使 用 Spring. 


SPRING DAOs (iBATIS 2.x) 


SPRING DAO 依 赖 于 Spring 框架 .他 们 继承 Spring 的 SqlIMapClientDaoSupport 类 通 
过 Spring 容器 构造 DAO. 


GENERIC-CI DAOs (iBATIS 2.x) 


GENERIC-CI DAO 调 用 iBATIS 的 SqlMapClient 接 口 .该 接口 的 实例 是 通过 构造 函数 
注入 . 


GENERIC-SI DAOs (iBATIS 2.x) 


GENERIC-SI DAO 调 用 iBATIS 的 SqlIMapClient 接 口 .该 接口 的 实例 是 通过 setter 注 入 . 


Example 类 使 用 说 明 

Example 类 指定 如 何 构 建 一 个 动态 的 where 子 句 . 表 中 的 每 个 hon-BLOB 列 可 以 被 包 
括 在 where 子 名 中 .例子 是 展示 此 类 用 法 的 最 好 方式 . 

Example 类 可 以 用 来 生成 一 个 几乎 无 限 的 where 子 句 . 


Example 类 包含 一 个 内 部 静态 类 Criteria 包含 一 个 用 anded 组 合 在 where 子 
名 中 的 条 件 列表 . Example 类 包含 一 个 List&1lt;Criteria&gt; 属性 ,所 有 内 部 类 
Criteria 中 的 子 句 会 用 ored 组 合 在 一 起 . 使 用 不 同属 性 的 Criteria 类 允许 您 生 
成 无 限 类 型 的 where 子 句 . 

创建 Criteria 对 象 可 以 使 用 Example 类 中 的 createCriteria() 或 者 
or() .如 果 Criteria 对 象 是 用 createCriteria() 创建 的 ， 它 会 自动 为 
List&lt;Criteria&gt; 属性 添加 一 个 Criteria 对 象 - 这 使 得 它 更 容易 写 一 
个 简单 的 where 子 句 ， 如 果 您 不 需要 or 或 者 其 他 几 个 子 句 组合 的 话 .用 
or(Criteria criteria) 方法 创建 Criteria 对 象 , 方法 里 的 criteria 对 
象 会 被 添加 进 Criteria 对 象 的 列表 中 . 


重要 我 们 推荐 您 只 使 用 or() 方法 创建 Criteria 对象 . 我 们 相信 这 种 方法 使 
代码 更 有 可 读 性 . 


简单 查询 
这 个 例子 展示 了 如 何 用 生成 后 的 Example 类 去 生成 一 个 简单 的 where 子 句 : 


TestTableExample example = new TestTableExample(); 


example.createCriteria().andFieldiEqualTo(5); 


作为 另 一 种 选择 , 下 面 的 方式 也 是 可 以 的 : 


TestTableExample example = new TestTableExample(); 


example.or().andFieldiEqualTo(5); 


在 上 面 的 例子 中 , 动态 生成 的 where 子 名 是: 


where fieldi = 5 


下 面 的 例子 展示 了 如 何 用 生成 后 的 Example 类 去 生成 一 个 复杂 的 where 子 名 (用 到 了 
JSE 5.0 #32 #1): 


TestTableExample example = new TestTableExample(); 


example.or() 
.andFieldiEqualTo(5) 
.andField2IsNull(); 


example.or() 
.andField3NotEqualTo(9) 
.andField4IsNotNull(); 


List<Integer> field5Values = new ArrayList<Integer>(); 
field5Values.add(8); 
field5Values.add(11); 
field5Values.add(14); 
field5Values.add(22); 


example.or() 
.andField5In(field5Values ) ; 


example.or() 


.andField6Between(3, 7); 


在 上 面 的 例子 中 , 动态 生成 的 where 子 名 是: 


where (fieldi = 5 and field2 is null) 
or (field3 <> 9 and field4 is not null) 
or (fieldS in (8, 11, 14, 22)) 
or (field6 between 3 and 7) 


将 会 返回 满足 这 些 条 件 的 记录 结果 . 


去 重复 查询 

您 可 以 在 所 有 的 Example 类 中 调用 setDistinct(true) 方法 进行 强制 去 重复 查 
询 . 

Criteria 关 


Criteria 内 部 类 的 每 个 属性 都 包含 andXXX 方法 ， 以 及 如 下 的 标准 的 SQL 查 
询 方法 : 


e IS NULL - 指 相 关 的 列 必 须 为 NULL 
e IS NOT NULL - 指 相关 的 列 必 须 不 为 NULL 


= (equal) - 指 相关 的 列 必 须 等 于 方法 参数 中 的 值 

<> (not equal) - 指 相关 的 列 必 须 不 等 于 方法 参数 中 的 值 

> (greater than) - 指 相关 的 列 必须 大 于 方法 参数 中 的 值 

>= (greater than or equal) - 指 相关 的 列 必须 大 于 等 于 方法 参数 中 的 值 

< (less than) - 指 相 关 的 列 必须 小 于 于 方法 参数 中 的 值 

<= (less than or equal) - 指 相关 的 列 必须 小 于 等 于 方法 参数 中 的 值 

LIKE - 指 相关 的 列 必须 "ike" 方法 参数 中 的 值 . 这 个 方法 不 用 必须 加 入 '%', 您 
必须 设置 方法 参数 中 的 值 . 

NOT LIKE - 指 相 关 的 列 必 须 "not like" 方法 参数 中 的 值 . 这 个 方法 不 用 必须 加 
A '%', 您 必须 设置 方法 参数 中 的 值 . 

BETWEEN - 指 相关 的 列 必 须 在 "between" 方法 参数 中 的 两 个 值 之 间 . 

NOT BETWEEN - 指 相关 的 列 必须 不 在 "not between" 方法 参数 中 的 两 个 值 之 
i]. 

IN - 指 相关 的 列 必须 在 传 入 的 方法 参数 的 list 中 . 

NOT IN - 指 相关 的 列 必须 不 在 传 入 的 方法 参数 的 list 中 . 


扩展 Example 类 


在 菜 些 情况 下 可 能 需要 扩展 自动 生成 的 example。 您 可 能 希望 添加 特定 数据 库 查询 
obec: ROWNUM 支 持 ), 或 添加 除 自动 生成 外 的 查询 条 件 ( 如 不 区 分 大 小 写 查 
询 )。 在 这 种 情况 下 ， 您 需要 扩展 自动 生成 example 类 来 添加 这 些 额外 的 查询 条 件 。 


一 般 原 则 


MyBatis Generator (MBG) 一 般 情 况 下 一 个 表 名 对 应 一 个 自动 生成 "example" 类 ,除非 
您 特殊 配置 。"example" 类 动态 生成 where 条 件 被 用 于 xxxByExample 方法 。 


标准 的 "example" 类 包 a 能 。 在 这 种 情况 下 ,程序 特定 


您 添加 额 外 条 件 查询 荔 ; 能 。 这 可 能 需要 添加 非 标 准 条 件 查询 或 在 where 条 besa 
数据 库 特定 功能 。 


自动 生成 "example" 类 中 包含 一 个 内 部 类 实现 where 条 件 查 询 功 能 。 内 部 类 命名 
为 GeneratedCriteria ° MBG 同 时 也 生成 了 内 部 类 Criteria 继承 
了 GeneratedCriteria ,您 可 以 使 用 它 在 example 类 中 添加 您 想 要 的 功能 。 
Eclipse 插件 不 会 删除 Criteria 类 新 增 代码 ( 注 : 只 有 Eclipse 插件 ,并 且 有 注释 和 时 
间 惟 等 要 求 才 能 自动 合并 ), 因 此 您 无 需 担 心 新 增 代码 丢失 。 
例如 ,有 一 个 表 叫 CUSTOMER。 通 常 ,MBG 生 成 一 个 名 为 CustomerExample 的 
类 。 在 CustomerExample 类 中 添加 额外 功能 , 需 
在 CustomerExample.Criteria 类 中 新 增 方法 。 


扩展 vs 插件 

如 果 您 经 常 扩展 自动 生成 类 , 写 一 个 插件 来 实现 该 功能 比 手工 编写 扩展 类 代码 更 方 

便 。 下 面 (标题 "单条 件 参数 "的 插件 类 能 够 完成 单 参数 查询 
org.mybatis.generator.plugins.CaseInsensitiveLikePlugin ° 

添加 条 件 语句 

MBG 自 动 生成 SQL 在 运行 允许 创建 无 限制 where 条 件 。 为 了 完成 这 个 ,自动 生成 SQL 


支持 四 大 类 型 条 件 语句 。 对 应 每 种 类 型 的 SQL 语 句 ，GeneratedCriteria 内 部 有 
一 个 对 应 的 方法 用 于 添加 一 个 动态 的 where 条 件 。 


1. 简单 字符 串 替 换 
在 使 用 这 种 类 型 的 条 件 查询 时 不 需要 参数 对 象 替 换 wWhere 条 件 中 。 例 妈 


FIRST_NAME is null LAST_NAME is not null 


此 条 件 语句 GeneratedCriteria RAK: 
addCriterion(String anyString) 
LP "anyString" <= #  # Bt where F 4) o HA KE SERA o 
fal ho, ERAS JA SOUNDEX H žr ZARR KD HE o MYSAL F,R 8] Ke: 
SOUNDEX(FIRST_NAME) = SOUNDEX('frod') 
此 种 查询 太 复杂 ， 可 以 考虑 使 用 另外 一 个 方法 ,这 种 简单 字符 串 替换 必须 插入 到 
where 条 件 中 。 在 内 部 类 Criteria 中 添加 如 下 方法 : 


public Criteria andFirstNameSoundsLike(String value) { 
StringBuffer sb = new StringBuffer("SOUNDEX(FIRST_NAME) = SOUN 
DEX('"); 
sb.append(value); 
sb.append("')"); 


addCriterion(sb.toString()); 


return this; 


} 


下 面 代码 是 在 selectByExample 方法 中 使 用 了 刚才 新 增 的 方法 : 


CustomerExample example = new CustomerExample(); 
Criteria criteria = example.createCriteria(); 
criteria.andFirstNameSoundsLike("frod"); 

List results = selectByExample(example) ; 


这 种 方法 可 以 添加 任何 条 件 语句 到 Where 子 名 中 。 然 而 ,由 于 需要 保证 不 同 数据 类 型 
的 正确 (最 明显 的 日 期 、 时 间 和 时 间 戳 ), 所 以 最 好 使 用 参数 替换 。 同 时 , 这 样 操作 暴 
露 过 多 的 方法 会 导致 SQL 注入 问题 。 如 果 可 能 ,我 们 建议 使 用 下 面 列 出 的 方法 之 一 。 
2. 单条 件 参 数 
使 用 这 种 类 型 作为 条 件 语句 ,一 个 参数 替换 Where 条 件 。 例 如 

FIRST_NAME = ? LAST_NAME &lt;&gt; ? 

自动 生成 Criteria 类 条 件 方法 如 下 : 

addCriterion(String anyString,Object anyObject,String propertyName ) 
Where: 
anyString 
4% dewhere AAT 4 ,4e:upper(FIRST_NAME) like 


anyObject 

条 件 值 

propertyName 

条 件 列 名 ,用 于 排除 潜在 错误 。 

该 方法 用 于 单一 参数 where 条 件 。 

例如 ,假设 您 想 特定 列 不 区 分 大 小 写 查 询 , 在 MySQL 中 查询 条 件 如 下 
upper(FIRST_NAME) like ? 

此 方法 适合 单个 参数 功能 -一 个 参数 一 个 参数 值 。 将 下 面 方 法 添加 


到 ExtendedCriteria 中 : 


public ExtendedCriteria andFirstNameLikeInsensitive(String value 


{ 
addCriterion("upper(FIRST_NAME) like", 
value.toUpperCase(),"firstName"); 


return this; 


} 


下 面 代 码 是 在 selectByExample 方法 中 使 用 了 刚才 新 增 的 功能 


ExtendedExample example = new ExtendedExample(); 
ExtendedCriteria criteria = (ExtendedCriteria) example.createCri 
teria(); 

criteria.andFirstNameLikeInsensitive("fred%") ; 

List results = selectByExample(example); 


3. 列表 条 件 
列表 条 件 适 用 于 where 条 件 中 多 个 值 的 情况 。 例 如 : 


FIRST_NAME IN (?,?,?) LAST_NAME NOT IN (?,?,?,?) 


由 于 包含 了 "in" and "not in" 这 样 的 标准 查询 条 件 ,因此 使 用 起 来 不 太 灵 活 。 然 而 
在 Criteria 类 中 您 会 发 现 有 相应 的 方法 ,如 下 : 


addCriterion(String anyString,List listOfObjects,String propertyNam 
Where: 
anyString 
替换 where 条 件 参 数 ,如 :FIRST_NAME IN 
listOfObjects 


list 对 象 值 蔡 换 条 件 值 (在 list 前 有 一 个 开始 的 括号 ， 一 个 结束 括号 在 list 后 )。 
propertyName 
条 件 列 名 ,用 户 排除 潜在 错误 。 


4. Between 条 件 


Between 条 件 参 数 适用 于 where 条 件 特定 的 格式 。 例 如 : 
FIRST NAME BETWEEN ? AND ? LAST NAME NOT BETWEEN ? AND ? 


由 于 包含 了 "between" and "not between" 这 样 的 标准 查询 条 件 , 因 此 使 用 起 来 不 太 灵 
活 。 然 而 在 Criteria 类 中 您 会 发 现 有 相应 的 方法 ,如 下 : 


addCriterion(String anyString, Object object1,Object object2,String | 
Where: 
anyString 
替换 where 条 件 参 数 ,如 :FIRST_NAME BETWEEN 
object1 
替换 Where 条 件 第 一 个 参数 值 (object1 后 会 自 带 一 个 "and" 连 接 词 ) 。 
object2 
替换 Where 条 件 第 二 个 参数 值 (object2 前 会 自 带 一 个 "and" 连 接 词 ) 。 
propertyName 
条 件 列 名 ,用 户 排除 潜在 错误 。 


使 用 注意 事项 


不 同 数据 库 使 用 注意 事项 。 


DB2 

MySql 
Oracle 
PostgreSQL 


请 让 我 们 知道 您 所 使 用 的 数据 库 ,我 们 很 乐意 将 信息 添加 到 本 节 以 供 将 来 参考 。 


DB2 使 用 注意 事项 


LONG VARCHAR 字段 


默认 情况 下 MyBatis 将 LONG VARCHAR FARA A java.lang.String 类 型 , 数 
据 库 字段 映射 为 jdbcType="LONGVARCHAR" 。 这 样 映射 会 导致 DB2 在 检索 数据 时 
发 生 错 误 。DB2 ALONG VARCHAR 字 段 应 该 被 映射 为 java.lang.String 类 
型 ， 数 据 库 类 型 应 该 是 jdbcType="VARCHAR" 。 为 了 解决 该 问题 ,使 

用 &1lt;columnOverride&gt; 配置 如 下 : 


<table schema="DB2ADMIN" tableName="ALLTYPES" > 
<columnOverride column="LONG VARCHAR_FIELD" javaType="java.1 
ang.String" jdbcType="VARCHAR" /> 
</table> 


MySal 使 用 注意 事项 


无 符号 类 型 


MySql 支 持 有 符号 ， 无 符号 ， 数 字 类 型 字段 。 这 些 不 是 JDBC 类 型 ， 因 此 MyBatis + 
成 器 不 能 自动 转换 这 种 类 型 的 字段 。JAVA 数 据 类 型 都 是 有 符号 的 ， 当 使 用 无 符号 
类 型 时 这 就 会 导致 缺失 精度 。 可 以 使 用 &1lt;columnOverride&gt; 解决 MySql 无 
符号 数值 类 型 的 字段 。 下 面 是 一 个 如 何 处 理 无 符号 bigint 字 段 类 型 例子 : 


<table tableName="ALLTYPES" > 
<columnOverride column="UNSIGNED_BIGINT_FIELD" javaType="jav 
a.lang.Object" jdbcType="LONG" /> 
</table> 


您 还 必须 自己 强制 将 返回 值 转换 为 适当 的 类 型 (在 上 面 这 种 情况 下 ， 需 要 转换 为 
java.math.BigInteger )° 


Oracle 使 用 注意 事项 


HALA 


如 果 您 想 要 一 个 表 生 成 对 象 公共 同 义 词 ， 您 实际 生成 的 对 象 执 行 真 正 的 表 名 -然后 在 
行 的 时 候 修 改 表 名 。MyBatis 自 动 生成 器 支持 这 样 。 


例如 ， 假 设 有 一 个 公共 表 名 为 "FRED" 指 向 表 "HR.EMPLOYEES"。 下 面 的 配置 是 基 
于 HR.EMPLOYEES 生 成 的 对 象 ， 但 运行 的 时 候 SQL 只 会 指向 FRED: 


<table schema="HR" tableName="EMPLOYEES"> 
<property name="ignoreQualifiersAtRuntime" value="true" /> 
<property name="runtimeTableName" value="FRED" /> 

</table> 


Oracle 长 数据 类 型 


Oracle 的 JDBC 了 驱动 会 将 LONG 类 型 的 列 当 成 JDBC 的 LONGVARCHAR 类 型 。 由 于 
Oracle 驱 动 程序 不 支持 ，MyBatis 将 映射 为 CLOB。 因此 在 使 用 长 数据 类 型 时 ， 您 
应 该 在 生成 器 上 配置 一 个 列 的 重 写 将 其 映射 到 JDBC 的 VARCHAR 类 型 。 


PostgreSQL 使 用 注意 事项 


区 分 大 小 写 


PostgreSQL 所 有 的 数据 库 标 识 符 ( 表 名 ,模式 名 , 列 明 等 ) 是 区 分 大 小 写 的 。 此 外 ， 
PostgreSQL 明 显 的 偏好 所 有 标识 符 使 用 小 写字 母 。 如 果 您 使 用 全 部 小 写 标识 符 的 
PostgreSQL > MyBatis Generator 不 需要 任何 额外 的 配置 就 会 发 现 表 并 且 编 写 正 确 
的 SQL。 如 果 您 使 用 混合 或 者 大 写 模 式 ， 您 需要 适当 配置 MyBatis Generator: 


o 当 您 的 表 或 模式 是 大 小 写 混 合 或 全 部 大 写 时 ， 使 用 delimitIdentifiers 配 
Fo 
Es 

© 为 每 个 大 小 写 混合 或 大 写 的 列 可 以 指定 &lt;columnOverride&gt; 元 素来 指 
定 列 ， 或 者 您 可 以 指定 delimitAllcolumns 属性 来 指定 所 有 的 列 。 


例子 1 


<table schema="HR" tableName="Employees" 
delimitIdentifiers="true" delimitAl1Columns="true"/> 


例子 2... 


<table schema="HR" tableName="Employees" delimitIdentifiers="t 
rue" > 


<columnOverride column="EmployeeId" delimitedColumnName="tru 
e" /> 

<columnOverride column="EmployeeName" delimitedColumnName="t 
rue" /> 


</table> 


本 节 收 集 了 一 些 和 MyBatis Generator 有 关 的 有 用 的 技术 主题 。 


从 源码 构建 

扩展 MyBatis Generator 
执行 插件 

日 志 信息 


从 源码 构建 


所 有 MyBatis 代码 生成 器 (MBG) 发 行 版 都 包含 源 代码 。 运行 时 的 唯一 依赖 是 
ant.jar -为 了 圆满 完成 包含 的 Ant 任 务 。 它 是 直接 从 源 代码 编译 MBG - 只 需要 
解压 发 行 包 并 使 用 您 喜欢 的 工具 进行 编译 。 


MBG 发 行 包 不 包含 编译 期 间 的 测试 ， 或 者 编译 期 间 必 须 部 分 的 其 他 的 类 。 如 果 您 
Ta 些 类 ， 或 者 使 用 github 上 最 新 版 本 的 源码 编译 MBG， 那 么 按照 下 面 的 步骤 
操作 : 


. MBG 用 Apache Maven 构 建 。 首 先 您 必须 能 运行 mMaven。 如 果 您 不 熟悉 
Maven， 这 里 有 最 简单 的 步 (针对 Windows): 
i 从 这 里 http://maven.apache.org/ 下 载 Maven 发 行 包 

ii, 解压 发 行 包 到 一 个 方便 的 位 置 。 

i 设置 环境 变量 和 PATH © 示例: set JAVA_HOME=C:\JavaTools\jdk1.6.0_ 17 
set M2 HOME=C:\JavaTools\apache-maven-3.0 set 
PATH=%PATH%;%M2_HOME%)\bin; 

2. 使 用 git 从 下 面 的 位 置 检 出 代码 https://github. dy 
3. 在 检 出 的 目录 下 打开 CMD 执 行 mvn clean install 命令 ， 或 者 其 他 的 
Maven 命 令 。 


扩展 MyBatis Generator 


MyBatis Generator (MBG) 是 专 为 扩展 性 设计 的 。 所 有 的 代码 生成 使 用 Java 和 
XML 元 素 简 单 的 DOM 表 示 执 行 。 


Java 的 DOM 和 包含 在 org.mybatis.generator.api.dom.java & 
该 XML DOM 包含 在 org.mybatis.generator.api.dom.xml & 


这 些 类 不 足以 实现 每 个 可 以 想象 到 的 代码 生成 的 可 能 性 ， 但 是 用 于 生成 简单 到 中 等 
复杂 Java 和 XML 代码 相当 有 用 的 。 


在 配置 文件 中 使 用 的 选项 ， 您 可 以 提供 自己 的 许多 关键 代码 生成 接口 的 实现 。 您 也 
可 以 继承 任何 提供 的 实现 来 提供 定 制 的 行为 。 这 个 页 面 将 介绍 可 用 的 公共 API， 并 
提供 进一步 调查 源 代 码 的 指示 。 如 果 您 对 如 何 扩展 MBG 有 任何 的 困难 ， 您 可 以 在 支 
持 的 邮件 列表 mybatis- ei 发 送信 息 。 


扩展 与 插入 


虽然 本 网 页 eee ie ees A sr 这 将 是 很 容易 通过 使 用 
插件 扩展 MBG 。 查 阅 开发 插件 的 参考 页 面 了 解 更 多 信息 


代码 生成 的 主要 扩展 点 是 org.mybatis.generator.api. IntrospectedTable ° 
实现 一 个 代码 生成 器 是 一 个 有 意义 的 任务 ， 只 有 当 您 想 要 完全 取代 MBG 的 代码 生成 
活动 时 才 考 虑 。 自 从 Abator 的 原始 版 本 以 来 ， 很 少 出 现 有 增强 请 求 无 法 通过 一 个 插 
件 来 处 理 的 。 


扩展 点 


MBG 提 供 了 许多 不 同 的 扩展 点 。 以 下 部 分 列 出 扩展 MBG 的 不 同方 法 ， 并 描述 了 
以 实现 与 不 同 的 扩展 活动 的 类 型 。 如 果 您 需要 一 些 了 解 不 同 的 选 et BO 
自由 的 在 用 户 邮件 列表 上 询问 问题 。 


org.mybatis.generator.api.IntrospectedTable 


IntrospectedTtable 是 一 个 可 以 扩展 用 于 提供 和 MBG 供 给 的 版 本 不 同 的 代码 生 
成 的 抽象 类 。 这 种 实现 的 一 个 很 好 的 例子 是 基于 一 个 FreeMarker 的 或 Velocity 模板 
的 实现 。 在 大 多 数 其 他 情况 下 ， 编 写 插件 是 一 个 更 好 途径 。 


如 果 您 选择 扩展 这 个 类 ， 您 必须 提供 代码 来 生成 Java 和 XML 文件 。 您 可 以 选择 生成 
文 些 文件 的 技术 。 IntrospectedTable 基础 类 持 有 的 一 

个 org.mybatis.generator.internal.rules.Rules 实例 可 查询 许多 用 于 代码 
生成 的 规则 ° 


MBG 提 供 反 射 表 的 几 种 实现 。 实 现 基 于 &lt;context&gt; 元 素 
的 targetRuntime 属性 值 。 在 大 多 数 情况 下 ， 继 承 下 面 的 一 个 内 置 的 扩展 比 从 头 
开始 创建 一 个 实现 会 容易 很 多 。 下 表 显 示 了 内 置 的 实现 : 


TargetRuntime 实现 

gr 
er CR org.mybatis.generator.codegen.mybatis3.Introspecte 
Ibatis2Java2 org.mybatis.generator.codegen.ibatis2.Introspected 
Ibatis2Java5 org.mybatis.generator.codegen.ibatis2.Introspected 


如 果 您 选择 实现 此 扩展 点 ， 指 定 alt;context&gt; 元素 的 targetRuntime 属性 
为 您 的 实现 类 的 完全 限定 类 名 。 


org.mybatis.generatorapi.IntrospectedColumn 


IntrospectedColumn 是 一 个 包含 列 的 信息 的 类 ， 因 为 它 是 一 个 从 数据 库 返 回 的 
元 数据 类 。 在 某 些 罕见 的 情况 下 ， 可 能 需要 重 写 这 个 类 来 提供 自己 的 - 特别 是 如 果 
您 创建 了 一 套 新 的 代码 生成 器 。 

如 果 您 选择 实施 此 扩展 点 ， 指 定 &lt;context&gt; 元 素 
的 introspectedColumnImp1 属性 为 您 实现 类 的 完全 限定 类 名 。 


org.mybatis.generator.api.JavaTypeResolver 


MBG 在 内 省 数据 库 时 调用 这 个 接口 的 方法 将 JDBC 类 型 映射 到 Java 类 型 。 这 个 接口 
的 默认 实 

现 org.mybatis.generator.internal.types.JavaTypeResolverDefaultImpl 
。 您 可 以 提供 自己 的 实现 ， 并 且 黑 认 的 实现 已 被 设计 为 可 扩展 。 


提供 您 自己 的 实现 ， 在 XML 配置 中 指定 全 限定 的 类 名 : 


<javaTypeResolver type="mypackage.MyImplementation”> ...</ j 
avaTypeResolver> 


org.mybatis.generator.api.ShellCallback 
MBG 调 用 这 个 接口 的 方法 来 执行 功能 ， 它 不 能 自己 做 。 最 重要 的 功能 是 : 
o 翻译 项 ?3 目 / 包 到 一 个 目录 结构 
eo 合并 事件 中 的 Java 源 文件 同名 的 现 有 的 Java 文 件 /程序 包 是 否 存在 。 
这 个 接口 的 默认 实 
现 org.mybatis.generator.internal.DefaultShellCallback ° RU EI f 


单 的 将 项 目 和 包 连 接 在 一 起 ， 如 果 需 要 则 创建 必要 的 包 目 录 。 默 认 的 实现 不 支持 
Java 文 件 的 合并 ， 并 将 覆盖 或 忽略 文件 。 


您 可 以 提供 自己 的 实现 。 如 果 您 想 将 MBG 集 成 到 一 些 其 他 的 环境 中 ， 这 六 
的 一 个 需要 编写 的 类 。 例 如 ，Eclipse 插 件 提供 的 实现 在 Eclipse 环境 中 运行 
支持 Java 文 件 的 合并 。 


提供 您 自己 的 实现 ， 提 供 有 关 构 造 函 数 的 接 

口 org.mybatis.generator .api.MyBatisGenerator 的 alan 这 个 不 能 通 
过 XML 来 配置 。 如 果 您 提供 自己 的 实现 此 接口 的 话 ， 我 们 假设 您 也 提供 了 一 些 附 加 
的 代码 (如 一 个 新 的 Ant 任 务 ) 来 运行 您 的 实现 。 


年 是 最 重要 
时 ， 


它 


org.mybatis.generator.api.ProgressCallback 


MBG 调 用 这 个 接口 的 方法 在 文件 的 生成 〈 长 时 间 运 行 的 进程 ) 中 报告 进度 。 这 个 接 
口 的 默认 实现 a mybatis.generator.internal. Ou S CR 
是 忽略 所 有 的 进度 消息 。 您 可 以 提供 此 接口 的 实现 ， 支 持 进度 通知 和 取消 代码 生 
成 o 

4 & X&MBG ZI 3 an 实现 此 接口 将 是 重要 的 。Eclipse 的 插件 提供 此 接口 挂 
接 到 Eclipse 的 进度 通知 系统 的 实现 。 


提供 您 自己 的 实现 ， 

在 org. Ds generator .api.MyBatisGenerator.generate() 的 一 个 方法 调 
用 上 提供 其 中 一 个 接口 的 实例 。 这 个 不 能 通过 XML 来 配置 。 同 样 ， 我 们 假设 ， 如 果 
您 提供 自己 的 实现 此 接口 ， 那 么 您 也 提供 了 一 些 附加 代码 (如 新 的 Ant 任 务 或 [DE 集 
成 ) 来 运行 您 的 实现 。 


开发 插件 


插件 可 用 于 修改 或 添加 到 由 MyBatis Generator 生成 的 对 象 。 插 件 必 须 实 

现 org.mybatis.generator.api.Plugin 接口 。 插件 接 ?? 口 所 含 许多 在 代码 生 
成 过 程 的 不 同 阶段 被 调用 的 方法 。 任 何 特定 的 插件 通常 不 需要 实现 整个 接口 。 
此 ， 大 多 数 插件 应 扩展 适配器 类 org.mybatis.generator.api.PluginAdapter 
。 适 配器 类 提供 基本 的 插件 支持 ， 并 为 大 多 数 的 接口 方法 (类似 于 Swing 适配器 
类 ) 提供 了 空 操作 的 方法 。 


MyBatis Generator 提供 了 几 个 插件 (都 在 
包 org.mybatis.generator.plugins F ) 。 所 提供 的 插件 展示 了 不 同类 型 的 可 
义 通 过 插件 完成 的 任务 。 插 件 的 源 代码 是 可 以 下 载 的， 也 可 以 在 线 浏览 这 里 o 


插件 的 生命 周期 


插件 有 一 个 生命 周期 。 插 件 在 代码 生成 过 程 的 初始 化 期 间 创建 并 且 在 这 个 过 程 中 的 
不 同 阶段 被 调用 。 下 面 的 列表 显示 了 插件 的 基本 生命 周期 : 


1. 插件 通过 默认 的 构造 函数 创建 
2. setContext 方法 被 调用 
3. setProperties 方法 被 调用 
4. validate 方法 被 调用 。 如 果 该 方法 返回 false ， 那 么 插件 中 的 其 他 方法 都 
不 会 再 被 调用 。 
对 于 配置 中 的 每 个 表 : 
i initialized 方法 被 调用 
ii，Java 客 户 端的 方法 : <sup>1,2</sup> 
i. clientXxxXMethodGenerated(Method, TopLevelClass, Introspe 
- 当 Java 客 户 端 实现 类 生成 的 时 候 这 些 方法 被 调用 . 
il. clientxxxMethodGenerated(Method, Interface, Introspected 
- 当 Java 客 户 端 接口 生成 的 时 候 这 些 方法 被 调用 。 
ii. clientGenerated(Interface, TopLevelClass, IntrospectedTa 
方法 被 调用 
iii， 模 型 方法 : <sup>1</sup> 
i. modelFieldGenerated , modelGetterMethodGenerated 
modelSetterMethodGenerated for each field in the class 
ii. modelExampleClassGenerated(TopLevelClass, IntrospectedTa 
iii. modelPrimaryKeyClassGenerated(TopLevelClass, Introspecte 
iv. modelBaseRecordClassGenerated(TopLevelClass, Introspecte 
v. modelRecordwithBLOBsClassGenerated(TopLevelClass, Intros 
iv. SQL 映射 方法 : <sup>1</sup> 
i. sqlMapxxxElementGenerated(XmlElement, IntrospectedTable) 
- 当 生 成 SQL 映射 的 每 个 元 素 的 时 候 这 些 方法 被 调用 
ii. sqlMapDocumentGenerated(Document, IntrospectedTable) 
iii. SqlMapDocument(GeneratedXmlFile, IntrospectedTable) 
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v. contextGenerateAdditionalJavaFiles(IntrospectedTable) 方法 被 
调用 
vi. contextGenerateAdditionalXmlFiles(IntrospectedTable) 方法 被 
调用 
6. contextGenerateAdditionalJavaFiles() 方法 被 调用 
7. contextGenerateAdditionalxmlFiles() 方法 被 调用 


注意 事项 : <sup>1</sup> -这 些 方法 将 被 包装 的 代码 生成 器 调用 。 如 果 您 提供 一 个 
自 定 义 的 代码 生成 器 ， 那 么 这 些 方法 将 仅 在 自 定义 代码 生成 调用 它们 时 调用 。 
<sup>2</sup> -Java 客 户 端的 方法 只 有 当 配 置 Java 客 户 端 生成 器 的 时 候 会 被 调用 。 


编写 插件 


实现 一 个 插件 ， 最 好 的 办 法 是 扩 
展 org.mybatis.generator.api.PluginAdapter 类 并 只 需要 履 盖 您 需要 的 插件 
方法 。 


插件 接口 方法 可 用 于 修改 默认 生成 的 代码 ， 或 添加 其 他 生成 的 代码 。Examples of 
things 可 以 通过 插件 实现 的 是 : 


给 生成 的 方法 添加 自 定义 注解 
给 生成 的 类 添加 其 他 方法 

给 生成 的 XML 文件 添加 其 他 元 素 
生成 额外 的 Java 文 件 

生成 额外 的 XML 文件 


contextXXX 方法 总 是 会 被 调用 。 其 他 方法 通过 包 代 码 生 成 器 调用 - 且 仅 当 表 中 的 
一 个 规则 将 会 生成 一 个 特定 元 素 时 。 例 如 ， 如 果 该 表 没 有 主键 ， 
modelPrimaryKeyClassGenerated(TopLevelClass, IntrospectedTable) 方 
法 将 不 会 被 调用 。 


方法 返回 一 个 boolean 可 用 于 绕 过 生成 代码 。 如 果 任 意 这 些 方 法 返回 false ， 
则 相关 的 项 目 不 会 被 添加 到 生成 的 代码 中 。 如 果 配 置 了 多 个 插件 ， 那 么 第 一 个 插件 
从 方法 返回 false 将 导致 MyBatis Generator 停 止 调 用 所 有 其 他 插件 的 方法 。 


如 果 您 有 一 个 关于 插件 的 想法 ， 可 以 自由 的 在 用 户 列表 问 有 关 的 问题 。 我 们 在 这 里 
提供 帮助 ! 


` 


日 志 信 息 


MyBatis Generator (MBG) 报告 日 志 记 录 的 几 种 不 同 的 方式 : 


e MBG 每 次 运行 的 es o 这些 消息 的 目的 是 告诉 用 户 

需要 注意 可 和 eae > 也 可 能 Ee 例如 文件 正在 被 入 总 KA FER 
命 的 配置 错误 等 等 等 么 配置 ， 警 告 总 是 会 显示 。 

° MBG 生 成 器 每 次 运行 的 J 能 会 或 者 不 会 显示 进度 信息 。 这 些 信息 用 来 告 
次 用 了 代码 生成 的 这 器 的 进度 信息 。 这些 信息 默认 不 显示 ， 但 是 可 以 通过 指 
定 -verbose 命令 行 参 数 进 pe 。 或 者 您 通过 Ant 任 务 运行 MBG， 您 可 以 通 
过 设置 verbose 属性 为 true ,这 样 Ant 就 会 运行 在 verbose 模 式 。 

。 最 后 ，MBG 将 生成 跟踪 (记录 ) 详 细 的 调试 消息 。 本 页 说 明 如 何 启 用 这 些 语句 。 


一 般 来 说 ，MBG 不 会 重复 消息 。 所 以 MBG 生 成 警告 的 时 候 这 个 警告 通 
Ke 在 某 些 情况 下 需要 启用 日 志 记 录 以 及 要 求 MBG 记 录 详 细 进 度 消息 
会 有 用 。 这 可 能 会 产生 大 量 的 输出 ， 但 是 仍然 会 提供 一 个 MBG 运 行 期 
部 事件 描述 。 


如 果 Log4J 在 运行 时 的 类 路 径 中 ，MBG 就 会 使 用 Apache Re 
khttp://logging.apache.org/log4j/ 获取 有 关 Log4J 的 详细 信息 云 行 
时 的 类 路 径 中 ，MBG 会 使 用 标准 的 Java 日 志 记 录 。 


即使 运行 时 类 路 径 中 存在 Log4J， 您 仍然 想 强制 使 用 标准 的 Java 日 志 记录 ， 您 可 以 
在 命 命令 行 参数 指定 -forceJavaLogging ， 或 者 当 您 通过 Java 执 行 MBG 时 使 用 执 
行 下 面 的 方法 : 


org.mybatis.generator.logging.LogFactory.forceJavaLogging(); 


重要 : 您 必须 将 上 面 的 方法 放 在 任何 MBG 代 码 之 前 。 


还 没 记 
时 候 可 能 


党 
的 
间 完 整 的 内 


提供 备用 的 实 


如 果 您 喜欢 使 用 不 同 的 日 志 实现 比 Log4J 的 或 标准 的 Java 日 志 记 录 ， 您 可 能 会 提供 
一 个 备用 实施 的 关键 日 志 界 面 如 下 : 


1. 创建 org. oien. generator .logging.Log 接口 的 实现 ， 实 现 您 选择 的 日 
志 实 现 的 关键 日 志方 法 。 

2. 创建 org.mybatis.generator.logging.AbstractLogFactory 接口 的 实 
现 ， 将 返回 您 Log 实现 的 实例 。 

3. 配置 MBG 通 过 调用 方法 来 使 用 新 的 LogFactory 
org.mybatis.generator.logging.LogFactory.setLogFactory(Abstractl 
并 提供 您 的 实例 AbstractLogFactory 实现 。 


配置 Log4J 日 志 


下 面 是 一 个 log4j 配 置 文件 示例 : 


# Set root logger 
log4j.rootLogger=INFO, A1 


# A1 is set to be a ConsoleAppender. 

log4j .appender .A1=org.apache.log4j .ConsoleAppender 

log4j .appender.A1.layout=org.apache.1log4j.PatternLayout 

log4j .appender.A1.layout.ConversionPattern=%-4r %-5p %c - %m%n 


# MBG logging configuration... 
log4j . logger .org.mybatis.generator=DEBUG 


这 个 文件 指示 Log4J 将 MBG 所 有 调试 信息 输出 到 控制 台 。 要 使 用 此 文件 : 


1. 运行 时 类 路 径 的 根 目 录 创 建 一 个 名 为 log4j.properties 的 文件 
2. 将 上 面 的 条 目 复 制 到 新 文件 

3. 运行 MBG 时 ，Log4J 的 JAR 文 件 也 需要 在 运行 时 类 路 径 

您 应 该 可 以 在 控制 台中 看 到 很 多 日 志 信 息 。 


p 果 您 喜欢 ， 您 也 可 以 配置 log4j 任 何其 他 支持 的 方法 。 


配置 Java 日 志 记 录 
下 面 是 一 个 Java 日 志 记 录 配 置 的 示例 文件 : 


# 指定 root logger 要 创建 的 处 理 程序 
# (所 有 的 loggers 都 是 root logger 的 孩子 ) 
handlers = java.util.logging.ConsoleHandler 


# A root logger 设置 默认 日 志 记 录 级 别 
. level = INFO 


# Set the default logging level for new ConsoleHandler instances 
java.util.logging.ConsoleHandler.level = ALL 


# Set the default formatter for new ConsoleHandler instances 
java.util.logging.ConsoleHandler.formatter = java.util.logging.sS 
impleFormatter 


# Set the default logging level for the logger named org.mybatis 


. generator 
org.mybatis.generator.level = FINE 


这 个 文件 将 指导 Java 写 的 所 有 MBG 调 试 消息 到 控制 台 。 要 使 用 此 文件 : 
1. 创建 一 个 名 为 logging.properties (或 者 您 喜欢 的 任何 文件 名 ?3) 的 文 


件 。 该 文件 可 以 在 文件 系统 中 存在 的 任何 地 方 (例如 ， 在 一 个 \temp A 


RK) ° 
2. 将 上 述 条 目 复制 到 新 文件 
3. 运行 MBG 时 带 上 这 个 VM 参 数 : 
-Djava.util.logging.config.file=\temp\logging.properties 
您 使 用 的 实际 的 文件 名 2742 AR) 
在 控制 台中 您 将 看 到 许多 日 志 信息 。 


如 果 您 喜欢 ， 您 还 可 以 配置 Java 日 志 记 录 为 其 他 支持 的 方法 。 


提供 的 插件 


随 着 MyBatis 生 成 器 (MBG) 的 使 用 量 的 增加 ， 我 们 发 现 越 来 越 有 用 以 通过 插件 增 
加 功能 ， 而 不 是 添加 到 基本 代码 发 生 器 的 复杂 性 。 插 件 是 一 个 模块 化 的 ， 易 于 理解 
的 机 制 ， 继 承 MBG。 有 关 编 写 一 个 插件 的 更 多 信息 ， 请 参阅 实现 插件 。 有 关 配 置 

插件 的 信息 ， 请 参阅 <plugin> 


所 提供 的 插件 都 在 org.mybatis.generator.plugins 包 。 所 提供 的 插件 展示 不 
同类 型 的 可 以 完成 与 MBG 插 件 任 务 。 插 件 的 源 代码 可 以 和 MBG 一 起 下 载 ， 也 可 以 
在 线 浏览 这 里 o 


org.mybatis.generator.plugins.CachePlugin 


这 个 插件 在 生成 的 SQL 映射 中 增加 了 一 个 <cache> 元 素 。 这 个 插件 仅 用 于 MyBatis3 
目标 运行 时 环境 。 


这 个 插件 接受 下 列 属性 。 都 是 可 选 的 ， 并 且 ， 如 果 指 定 ， 则 值 将 被 直接 传递 到 相应 
的 属性 生成 的 <cache> 元 素 。 


cache_ eviction 
cache_flushinterval 
cache_readOnly 
cache_size 
cache_type 


所 有 属性 都 可 以 通过 指定 <table> 元 素 的 属性 来 覆盖 。 


org.mybatis.generator.plugins.CaselnsensitiveLike 
Plugin 

该 插件 PES 添加 方法 (实际 上 是 给 SCriteria 内 部 类 ) 来 支持 不 区 分 大 小 写 的 
LIKE 搜 索 。 这 表明 通过 插件 给 Example 类 添加 功能 ， 而 不 是 扩展 这 个 类 。 


org.mybatis.generator.plugins.EqualsHashCodePI 
ugin 
这 个 插件 给 由 MBG 生 成 的 Java 模 型 对 象 增 加 了 equals 和 hashCode 方法 。 


通过 这 个 类 生成 的 equals 方法 ， 在 大 多 数 情 况 下 是 正确 的 ， : 但 如 果 您 已 经 指定 了 
rootClass 可 能 是 不 正确 的 - 因为 我 们 的 equals 方 法 只 检查 它 知 道 的 字段 。 


org.mybatis.generator.plugins.MapperConfigPlugi 
n 

这 个 插件 生成 包含 对 MBG 所 生成 的 XML 了 映射 文件 的 框架 MapperConfig.xml 文 件 。 
此 文件 可 用 于 配置 的 MyBatis 3.X 环 境 。 

这 个 插件 接受 三 个 属性 : 


e fileName ?? (可 选 的 ) 生成 的 文件 的 名 称 。 如 果 没 有 指定 ， 默 认 
A “MapperConfig.xml” ° 

e targetPackage (必须 的 ) 生成 文件 放置 的 包 名 。 指 定 
像 'com.mycompany.sql" 这 样 的 值 。 

e targetProject (必须 的 ) 该 文件 应 放置 在 的 项 目 名 称 。 


注 : targetPackage 和 targetProject 遵循 sqlMapGenerator 配 置 元 素 
上 targetPackage 和 targetProject 的 相同 的 规则 。 


org.mybatis.generator.plugins.RenameExampleCla 
ssPlugin 

这 个 插件 通过 重 命名 由 MBG 生 成 的 Example 类 的 方法 演示 initialized 方法 的 用 
法 。 

这 个 插件 接受 两 个 属性 : 


e searchString (必须 的 ) ， 用 于 搜索 默认 生成 的 Example 的 名 称 的 正则 表达 
No 
e replaceString (必须 的 ) 揪 在 匹配 searchString 位 置 的 字符 串 。 


例如 ， 从 XxxExample 重 命名 生成 的 例子 类 xxxCriteria， 指 


定 实例 美元 searchString 和 标准 replaceString 


org.mybatis.generator.plugins.RowBoundsPlugin 


这 个 插件 将 添加 一 个 新 版 本 selectByExample 方法 接受 RowBounds 参数 。 这 支 
持 的 MyBatis RowBounds 函 数 ， 其 中 一 个 返回 的 结果 列表 可 以 在 长 度 受 到 限制 ， 并 
且 开 始 位 置 可 以 被 指定 。 这 可 以 是 在 分 页 应 用 中 是 有 用 的 。 


这 个 插件 仅 适用 于 MyBatis3 目 标 运 行 时 环境 。 
org.mybatis.generator.plugins.SerializablePlugin 


这 个 插件 给 由 MBG 生 成 的 Javas 添 加 了 java.io.Serializable 标记 接口 。 这 个 
插件 给 实体 类 增加 了 serialversionUID 字段 。 


重要 提示 : 这 是 一 个 简单 的 实现 java.io.Serializable 并 且 不 会 党 试 做 任何 版 本 的 类 。 
这 个 插件 接受 两 个 属性 : 
e addGWTInterface (可 选 的 ) True/False.。 如 果 为 true， 插 件 将 给 实体 对 象 
增加 谷歌 Web 工 具 包 (GWT) 的 IsSerializable 接口 。 软 认 值 是 false ° 
e suppressJavaInterface (必须 的 ) True/False。 如 果 为 true， 插 件 将 不 添 
加 java.io.Serializable 接口 。 这 是 对 于 其 中 对 象 应 该 是 可 序列 化 的 
GWT， 但 不 是 严格 意义 上 的 Java 的 场景 。 默 认 值 是 false。 


org.mybatis.generator.plugins.SqlMapConfigPlugi 
n 
这 个 插件 生成 包含 对 MBG 所 产生 的 SqlMap.xml 文 件 的 SqlMapConfig.xml 框 架 文 
件 。 此 文件 可 用 于 配置 的 iBATIS 2.x 的 环境 。 
这 个 插件 接受 三 个 属性 : 

e fileName ?? (可 选 的 ) 所 产生 的 文件 的 名 称 。 如 果 没 有 指定 ， 默 认 值 

是 “SqlIMapConfig.xml”。 
e targetPackage (必须 的 ) 放置 该 文件 的 包 名 。 指 定 


像 "com.mycompany.sq 这 样 的 值 。 
e targetProject ( 必须 的 ) 放置 该 文件 的 项 目的 名 称 。 


注 : targetPackage 和 targetProject 遵循 和 sqlMapGenerator 配 置 元素 上 
的 targetPackage 和 targetProject 相同 的 规则 。 


org.mybatis.generator.plugins.ToStringPlugin 


该 插件 给 实体 类 添加 toString() 方法 。 


org.mybatis.generator.plugins.VirtualPrimaryKeyPI 
ugin 

这 个 插件 可 用 于 指定 作为 主键 的 列 ， 即 使 它们 没有 在 数据 库 中 被 定义 为 主键 列 。 这 
是 在 数据 库 表 没 有 定义 主 的 情况 下 非常 有 用 。 通 常情 况 下 ， 如 果 没 有 主键 ，MBG 将 
产生 一 组 非常 有 限 的 方法 。 这 个 插件 可 以 用 来 启用 生成 的 完整 的 MBG 方 法 。 

要 使 用 该 插件 ， 添 加 属性 “virtualKeyColumns” 到 您 的 <table> 配 置 ， 设 置 值 为 应 被 视 


做 主键 的 用 各 号 或 空格 分 隔 的 列 名 列表 。 列 名 必须 和 数据 库 (通常 全 部 大 写 ) 返回 
的 列 名 完全 匹配 。 例 如 : 


<table tableName="foo"> 
<property name="virtualKeyColumns" value="ID1, ID2" /> 
</table> 


设计 理念 


此 工具 可 能 会 引发 一 些 哲 理性 问题 ， 因为 该 工具 是 更 侧重 于 数据 库 表 ， 而 不 是 实体 
类 。 我 们 将 采取 几 个 段落 来 谈论 这 种 做 法 。 


首先 ， 这 个 工具 做 什么 。 我 们 不 是 在 做 任何 有 关 项 目 应 该 或 不 应 该 是 结构 化 这 种 说 
法 的 。 在 一 般 情 况 下 我 们 支持 富 实体 类 ， 但 创建 一 个 富 实体 类 和 是 否 应 该 坚持 这 
种 模式 完全 不 是 一 码 事 。 


如 果 您 特定 的 设计 理念 是 实体 类 驱动 所 有 的 决策 ， 数 据 库 设计 是 性 从 于 实体 类 ， 那 
么 这 个 工具 - 和 MyBatis 本 身 - 可 能 不 适合 您 的 应 用 程序 。 在 这 种 情况 下 ， 我 们 建 
议 您 认真 考虑 Hibernate - 他 可 能 更 贴近 您 的 应 用 程序 和 设计 理念 。 


但 并 非 所 有 的 项 目 都 适合 这 种 模式 。 很 少 有 引 正 的 企业 级 应 用 程序 会 这 么 做 。 
MyBatis 对 那些 将 数据 库 表 设 计 和 实体 对 象 设 计 看 做 一 样 的 项 目 有 很 大 的 帮助 。 
MyBatis 不 是 对 象 关 系 映射 ， 并 且 不 会 尝试 去 持久 化 对 象 。 所 以 他 着 眼 于 应 用 开发 
人 员 编 写 SQL 和 数据 库 表 进 行 交 互 。 


在 大 型 或 企业 级 的 项 目 ， 其 中 的 许多 因素 是 很 常见 : 


e 数据 库 设计 往往 是 从 OO 实体 设计 一 个 单独 的 功能 (有 单独 的 管理 ) 

eo 数据 库 设计 者 没有 OO 工具 (比如 继承 ) ， 所 以 他 们 不 从 OO 考虑 。 

e 应 用 程序 设计 人 员 并 不 能 完全 控制 数据 库 表 的 最 后 形式 。 例如， 在 应 用 中 适合 
存在 于 一 个 对 象 的 数据 ， 在 数据 库 中 可 能 被 分 成 几 个 表 。 

o 数据 库 设 计 最 终 和 OO 设计 的 完全 不 同 ， 从 而 导致 表 和 对 象 之 间 的 明显 不 能 匹 
Be, o 


从 这 些 主要 的 指标 来 看 ， 对 您 的 应 用 来 说 MyBatis 是 一 个 非常 不 错 的 候选 工具 ， 
MyBatis Generator 可 以 在 这 类 项 目 起 到 重要 的 影响 。 那么 ， 在 这 种 情况 下 应 该 如 
何 使 用 MyBatis? 


数据 访问 对 象 (DAO) 模 式 仍 然 是 一 种 主要 的 模式 。 MyBatis Generator 可 以 生成 一 组 
基本 的 和 每 个 表 对 应 的 对 象 。 生成 的 代码 是 和 事务 无 关 的 。 这 意味 着 如 果 在 一 个 事 
务 中 涉及 多 个 表 参 与 ， 可 以 很 容易 的 扩展 生成 的 代码 。 或 者 您 可 以 创建 另 一 个 
DAO (或 服务 方法 ) ， 更 紧密 地 匹配 实体 对 象 的 持久 性 需求 ， 并 可 以 再 一 个 事务 中 
使 用 一 个 或 多 个 生成 的 对 象 。 


举 个 例子 ， 考 虑 一 个 典型 的 Order 对 象 ， 典 型 的 标题 和 细节 的 问题 。 在 某 些 环 
境 中 这 种 对 象 将 保存 到 至 少 四 个 表 - 两 个 关键 表 、" 标 题 " 表 和 "详细 信息 " 表 (再 次 声 
明 ， 我 们 不 做 任何 种 类 的 关于 这 是 否 "正确 "的 语句 设计 ， 只 在 陈述 一 个 事实 )。 您 的 
应 用 程序 还 应 与 Order 对 象 进行 交互 ,并且 可 能 在 某 个 地 方 〈 在 OrderDAO 或 者 
在 一 个 Service 对 象 ) 存在 一 个 saveOrder(Order order) 方法 该 方法 将 与 所 涉 
及 的 4 个 表 生 成 的 代码 进行 交互 。 


在 这 种 情况 下 ， 代 码 生成 器 给 我 们 带 来 什么 ? 有 以 下 几 种 : 


e 重用 (4A) -很 可 能 是 一 些 表 将 需要 从 不 同 的 DAO 或 者 Service 方 法 访问 。 
为 每 个 表 创建 一 个 DAO 可 以 促进 重用 和 应 用 程序 内 的 一 致 性 。 


o REEMA - 服务 层 通 常 在 应 用 程序 中 定义 持久 性 。 这 些 方法 可 以 很 快 稳定 。 
随 着 数据 库 设 计 的 发 展 : 
1， 代 码 可 以 很 快 的 随 着 表 的 改变 而 重新 生成 
2. Service 方 法 可 以 根据 需要 修改 
3. 更 高 层 的 应 用 程序 保持 不 变 
o 开发 者 的 效率 - 生成 基于 表 的 DAO 是 很 快速 、 可 重复 和 无 差错 的 。 开发 人 员 可 
以 专注 于 对 象 持久 化 和 可 能 需要 的 复杂 的 联接 查询 。 
eo 更 少 的 缺陷 - 因为 所 有 应 用 程序 中 最 繁 融 和 最 容易 出 错 的 部 分 (获得 SQL 匹配 
的 对 象 ) 是 自动 化 的 。 


Velocity 中 文 文档 


1. 关于 


Velocity 用 户 指 南 旨 在 帮助 页 面 设 计 者 和 内 容 提 供 者 了 解 Velocity 和 其 简单 而 又 强 
大 的 脚本 语言 (Velocity Template Language (VTL)) 。 本 指南 中 有 很 多 示例 展示 了 
用 Velocity 来 讲 动态 内 容 瞪 入 到 网 站 之 中 ， 但 是 所 有 的 VTL examples 都 同 演示 用 于 
所 有 的 页 面 和 模版 。 


感谢 选择 Velocity! 


2. 什么 是 Velocity? 


Velocity 是 一 个 基于 Java 的 模版 引擎 。 它 允许 web 页 面 设 计 者 引用 JAVA 代码 预定 义 
的 方法 。Web 设计 者 可 以 根据 MVC 模 式 和 JAVA 程序 员 并 行 工作 ， 这 意味 着 Web 设 
计 者 可 以 单独 专注 于 设计 良好 的 站 点 ， 而 程序 员 则 可 单独 专注 于 编写 底层 代码 。 
Velocity 将 Java 代码 从 web 页 面 中 分 离 出 来 ， 使 站 点 在 长 时 间 运 行 后 仍然 具有 很 好 
的 可 维护 性 ， 并 提供 了 一 个 除 JSP 和 PHP 之 外 的 可 行 的 被 选 方案 。 


Velocity 可 用 来 从 模板 产生 web 页 面 ，SQL, PostScript 以 及 其 他 输出 。 他 也 可 用 于 
一 个 独立 的 程序 以 产生 源 代 码 和 报告 ， 或 者 作为 其 它 系统 的 一 个 集成 组 件 。 这 个 项 
目 完成 后 ，Velocity 将 为 Turbine web 应 用 程序 框架 提供 模板 服务 。 
Velocity+Turbine 方案 提供 的 模板 服务 将 允许 web 应 用 按 引 正 的 mvc 模 式 进 行 开 


o 


3. Velocity 可 以 做 什么 ? 


3.1. Mud Store 示例 


假设 你 是 一 个 专门 销售 泥浆 (MUD) 的 在 线 商 店 的 页 面 设 计 者 。 我 们 称 他 为 "The 
Online Mud Store"。 生 意 很 好 。 客 户 订 购 各 种 各 样 的 类 型 和 数量 的 泥浆 。 他 们 使 用 
他 们 的 用 户 名 和 密码 登陆 到 商店 中 来 ， 就 可 以 浏览 他 们 的 订货 和 购买 其 他 东西 。 现 
在 ， 杰 土 陶 泥 正在 促销 ， 这 是 一 种 很 常用 的 泥巴 。 一 少 部 分 顾客 很 有 规律 的 购买 一 
种 亮 红 土 Bright Red Mud， 这 也 是 促销 产品 ， 但 是 不 太 常 用 ， 因 此 被 移 到 页 面 的 边 
缘 。 所 有 顾客 的 信息 都 在 数据 库 中 被 跟踪 ， 因 此 有 一 天 问题 出 现 了 : 为 什么 不 使 用 
Velocity 来 定位 目标 客户 ， 这 些 客户 对 某 种 类 型 的 产品 特别 感 兴趣 ? 


WOOO Ga i Ralglee t) LEA cial cae wi a 。 作 为 一 个 在 线 
泥巴 商店 的 站 点 设计 者 ， 以 想 在 客户 以 登陆 进展 点 后 就 看 到 它们 想 看 的 页 面 。 


你 遇 到 你 公司 的 软件 工程 师 ， ， 每 个 人 都 认为 $customer 将 保持 当前 登陆 进入 的 客户 
信息 ， 而 $mudsOnSpecial 将 士 当 前 所 有 促销 的 泥巴 。$flogger 对 人 象 包含 有 助 于 促 
ee ne ee ae 
工程 师 如 何 从 数据 库 中 取得 顾客 信息 ， 但 你 必须 知道 他 们 可 以 。 这 样 可 以 使 你 专注 
于 你 的 工作 而 软件 工程 师 则 忙于 他 们 自己 的 工作 o 


你 可 以 在 你 的 页 面 中 诬 入 如 下 的 VTL 语 句 : 


<HTML> 
<BODY> 
Hello $customer.Name! 
<table> 
#foreach( $mud in $mudsOnSpecial ) 
#if ( $customer.hasPurchased($mud) ) 
<tr> 
<td> 
$flogger.getPromo( $mud ) 
</td> 
</tr> 
#end 
#end 
</table> 


foreach 语 名 的 细节 将 进一步 细 说 ， 但 重要 的 是 这 个 短小 的 脚本 居然 可 以 在 你 的 站 点 
上 运行 。 当 有 一 个 倾向 于 亮 红 土 的 顾客 登陆 进来 时 ， 亮 红土 正在 促销 ， 这 就 是 这 个 
顾客 所 看 到 的 ， iets a 常 显 著 。 如 果 另 外 一 个 长 期 购买 赤 陶 土 的 顾客 登陆 
进来 ， 杰 陶土 促销 的 提示 信息 则 应 该 在 前 面 中 间 位 置 。 Velocity 是 非常 灵活 的 ， 受 
限 的 只 是 你 的 创造 力 。 


写 在 VTL 参 考 文 档 中 的 是 其 他 Velocity 元 素 ， 他 们 一 起 给 你 很 强大 的 能 力 和 灵活 性 
以 创建 很 好 的 站 点 。 待 你 更 加 了 解 这 些 元 素 ， 就 可 以 开始 释放 Velocity 的 强大 动 
力 o 


3.1. Mud Store 示例 
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4. Velocity 模板 语言 (VTL): 介绍 


Velocity 模板 语言 (VTL) 间 在 为 Web 页 面 结合 动态 内 容 提 供 最 容 
法 。 即 使 有 一 点 或 者 没有 编程 经 验 的 页 面 设 计 者 也 可 以 很 快 能 


VTL 使 用 引用 (references) 来 将 动态 内 容 说 入 Web 页 面 ， 每 个 变量 就 是 某 一 个 类 
型 的 引用 。 变 量 实际 上 是 一 个 可 以 调用 定义 在 java 代 码 中 的 内 容 的 引用 ， 或 者 它 可 
以 从 页 面 内 的 VTL 语 名 得 出 自身 的 值 。 下 面 是 一 个 例子 ， 说 明 可 以 说 入 到 HTML 文 
档 中 的 VTL 语 句 。 


易 、 简 单 和 简洁 的 方 
为 页 面 提供 动态 内 


#set( $a = "Velocity" ) 


这 个 VTL 语 名， 就 像 所 有 的 VTL 语 名 一 样 ， 以 # 字 符 开 始 ， 并 跟着 一 个 指令 Set。 当 
一 个 在 线 访 问 这 请 求 页 面 时 ，Velocity 模 伴 引 擎 在 页 面 内 搜索 所 有 # 字 符 ， 然 后 决 
定 是 哪 一 个 标记 了 VTL 语 句 的 开始 ， 哪 个 标记 不 需要 VTL 做 什么 动作 。 


# 字 符 后 面 紧 跟 一 个 指令 set.。set 指 令 使 用 一 个 括 在 括号 内 的 表达 式 --- 一 个 等 式 将 
一 个 值 指派 给 一 个 变量 。 变 量 在 等 号 的 左边 而 值 在 等 号 的 右边 。 

在 上 面 的 示例 中 ， 变 量 是 $a 值 是 Velocity。 这 个 变量 就 象 其 他 引用 一 样 ， 以 一 个 $ 字 
符 开 始 。 值 通常 在 引号 之 中 ， 对 Velocity 来 说 一 般 没 有 类 型 冲突 的 问题 ， 因 为 只 有 
字符 串 (基于 文本 的 信息 ) 可 以 传递 给 变量 。 


下 面 的 主要 规则 可 能 有 助 于 理解 Velocity 是 如 何 工作 的 : 引用 以 $ 开 头 用 于 取得 什么 
东西 ， 而 指令 以 # 开 始 用 于 做 什么 事情 。 


在 上 面 的 例子 中 ，#set 用 于 将 一 个 值 指派 给 一 个 变量 。 而 变量 $a 则 可 以 用 来 在 模板 
中 输出 "Velocity"。 


5. Hello Velocity World! 


一 旦 一 个 值 被 赋 给 一 个 变量 ， ee eae 。 在 下面 的 示例 中 ， 先 
合 变 量 $foo 赋 值 然 后 引用 它 


<html> 

<body> 

#set( $foo = "Velocity" ) 
Hello $foo World! 

</body> 

<html> 


这 个 页 面 的 结果 是 输出 "Hello Velocity World!" ° 


这 
为 了 使 包含 VTL 指令 的 语句 具有 可 读 性 ， 我 们 鼓励 每 个 VTL 语 和 句 在 一 个 新 行 开始 ， 
虽然 并 不 一 定 要 这 之 样 做 。 。Set 将 随后 深入 解释 。 


$ 


TON 


6. 注释 


可 以 用 注释 加 入 描述 性 文本 ， 他 们 并 不 在 模板 引擎 中 输出 。 注 释 可 以 有 助 于 你 的 记 
忆 或 者 想 其 他 人 解释 你 的 VTL 语 句 正在 做 什么 。 


## This is a single line comment. 


单行 注释 以 大 开始 ， 并 在 本 行 结 束 。 如 果 需 要 加 入 多 行 注释 ， 并 不 需要 加 入 很 多 的 
单行 注释 。 多 行 注释 ， 以 状 开 始 并 以 境 结 束 可 以 处 理 这 种 情况 。 


This is text that is outside the multi-line comment. 
Online visitors can see it. 


#* 

Thus begins a multi-line comment. Online visitors won't 
see this text because the Velocity Templating Engine will 
ignore it. 

XH 


Here is text outside the multi-line comment; it is visible. 


下 面 事 一 些 例子 说 明 单 行 注释 和 多 行 注释 如 何 工 作 。 


This text is visible. ## This text is not. 

This text is visible. 

This text is visible. #* This text, as part of a multi-line comm 
ent, 

is not visible. This text is not visible; it is also part of the 

multi-line comment. This text still not visible. *# This text is 
outside 

the comment, so it is visible. 

## This text is not visible. 


还 有 第 三 种 注释 ，VTL 注释 块 ， 可 以 用 来 存储 诸如 文档 作者 、 版 本 信息 等 。 


ea Sy 

This is a VTL comment block and 

may be used to store such information 
as the document author and versioning 
information: 

@author 

@version 5 

aH 


6. 注释 


955 


7. 引用 


VTL 中 有 三 种 类 型 的 引用 : 变量 ， 属 性 和 方法 。 作 为 使 用 VTL 的 设计 者 ， 你 和 你 的 
工程 师 必 须 在 饮用 的 特定 命名 上 取得 一 致 ， 以 便 在 你 的 模板 中 正确 的 使 用 他 们 。 


有 关 引 用 的 所 有 参数 都 处 理 为 字符 串 对 象 。Everything coming to and from a 
reference is treated as a String object. 假如 有 一 个 对 象 表示 $foo (比如 说 是 整 型 对 
象 )，Velocity 将 调用 其 toString() 方法 来 将 此 对 象 转换 为 一 个 字符 串 。 


7.1. 变量 Variables 


变量 的 简略 标记 是 有 一 个 前 导 "$" 字 符 后 跟 一 个 VTL 标识 符 (Identifier ) 组 成 。 一 
个 VTL 标识 符 必 须 以 一 个 字母 开始 (a .. z 或 A..Z)。 剩 下 的 字符 将 由 以 下 类 型 的 字 
符 组 成 : 


e #44 (a..z,A..Z) 
。 数字 (0 .. 9) 

e 连 字符 ("-") 

e 下 划 线 ("_") 


下 面 是 一 些 有 效 的 变量 引用 : 


$foo 
$mudSlinger 
$mud -slinger 
$mud_slinger 
$mudSlinger1 


当 VTL 引用 一 个 变量 时 ， 比 如 $foo， 变 量 可 以 从 模板 的 set 指 令 取得 值 ， 也 可 以 从 


Java 代码 中 取 和 得。 例如， 如 果 Java 变量 $foo 在 模板 被 请 求 的 时 候 具 有 值 bar， 则 
bar 将 替换 页 面 中 的 所 有 $foo 的 实例 。 或 者 ， 如 果 包 含 下 面 的 语句 : 


#set( $foo = "bar" ) 


紧 跟 指令 后 的 所 有 $foo 的 实例 的 输出 将 会 一 样 值 。 


7.2. 属性 


VTL 引 用 的 第 二 种 元 素 是 属性 ， 而 属性 具有 独特 的 格式 。 属 性 的 简略 标记 识 前 导 符 


$ 后 跟 一 个 VTL 标识 符 ， 在 后 跟 一 个 点 号 (".") 最 后 又 是 一 个 VTL 标识 符 。 这 是 一 些 有 
效 的 示例 : 


$customer .Address 
$purchase.Total 


请 看 第 一 个 例子 ，$customer.Address.。 他 有 两 种 意思 。 它 可 以 意味 着 ， 查 询 由 
customer 标 是 的 哈 希 表 并 按 关 键 字 Address 返 回 值 。 但 是 $customer.Address 也 可 能 
引用 一 个 方法 (下 述 ，$customer.Address 可 能 是 $customer.getAddress(). 的 缩 


写 。 当 一 个 页 面 被 请 求 时 ，Velocity 将 决定 这 两 种 可 能 到 底 是 哪 一 个 ， 然 后 返回 相 
应 的 值 a 


7.3. 六 法 


方法 在 JAVA 代码 中 定义 ， 并 作 一 些 有 用 的 事情 ， 比 如 运行 一 个 计算 器 或 者 作出 一 个 
决定 。 方 法 是 实际 上 也 是 引用 ， 由 前 导 符 "$" 后 跟 一 个 VTL 标识 符 ， 后 跟 一 个 VTL 
方法 体 (Method Body) ° VTL 方法 体 由 一 个 VTL 标识 符 后 跟 一 个 左 括 号 ， 再 跟 可 
选 的 参数 列表 ， 最 后 是 右 括号 。 下 面 是 一 些 有 效 的 方法 示例 : 


$customer .getAddress() 

$purchase.getTotal() 

$page.setTitle( "My Home Page" ) 

$person.setAttributes( ["Strange", "Weird", "Excited"] ) 


前 面 两 个 例子 -- $customer.getAddress()4#$purchase.getTotal() - 看 起 来 有 点 象 上 
面 属性 一 节 中 所 用 的 样子 ，$customerAddress 和 $purchase.Total.。 如 果 你 想 这 些 
例子 在 某 些 方面 相关 ， 那 你 就 对 了 。 


VTL 属性 可 以 为 VTL 方 法 用 作 简 略 标 记 。 属 性 $customerAddress 具 有 和 方法 
$customer.getAddress() 完全 一 样 的 效果 。 属 性 和 方法 的 主要 不 同 点 是 方法 中 可 以 
添加 参数 列表 。 


简略 标记 可 以 用 在 下 面 的 方法 中 : 
sun.getPlanets() 


$annelid.getDirt() 
$album.getPhoto( ) 


RAN RA A AK TAA RNR A TAR A AT ES Fo RFRA AH] O HK 
者 从 相册 中 返回 一 张 照 片 。 下 面 只 有 长 的 那个 标记 是 可 以 工作 的 方法 : 


$sun.getPlanet( ["Earth", "Mars", "Neptune"] ) 
HH 不 能 将 参数 列表 传递 给 $sun ,PLanets 


$sisyphus.pushRock() 
## Velocity 假定 我 意思 是 $Sisyphus .getRock() 


$book.setTitle( "Homage to Catalonia" ) 
HH 不 能 传递 一 个 参数 列表 


8. 形式 引用 符 Formal Reference Notation 
引用 的 简略 符号 如 上 所 述 ， 但 是 另外 还 有 一 种 引用 的 形式 符号 ， 示 例如 下 : 


${mudSlinger} 
${customer .Address} 
${purchase.getTotal()} 


在 大 多 数 情况 下 ， 我 们 将 使 用 引用 的 简略 符号 ， 但 在 一 些 情况 下 ， 也 需要 拥戴 哦 形 
式 引 用 符 以 便 正确 处 理 。 


假定 你 正在 纸 片 上 构件 一 个 句子 ， 将 使 用 $vice 作 为 句子 中 名 词 的 词根 。 我 们 的 目标 
是 允许 人 们 选择 词根 ， 然 后 产生 以 下 两 种 结果 之 一 : 
"Jack is a pyromaniac." 
或 者 
"Jack is a kleptomaniac." ° 
在 这 种 情况 下 ， 使 用 简略 符号 是 不 太 充 分 的 。 考 虑 到 下 面 的 例子 : 


Jack is a $vicemaniac. 


这 里 有 个 不 确定 性 ，Velocity 假定 $vicemaniac’ (而 不 是 $vice) 是 一 个 你 想 要 
使 用 的 标识 符 。 找 不 到 $vicemaniac 的 值 ， 他 将 返回 $vicemaniac。 使 用 形式 符号 便 
可 解决 这 个 问题 : 


Jack is a ${vice}maniac 


现在 Velocity 知道 $vice (而 不 是 $vicemaniac) 是 一 个 引用 。 形 式 符号 常用 在 饮用 
咋 模板 中 和 文本 直接 邻近 的 地 方 。 


9. 安静 引用 符 Quiet Reference Notation 


当 Velocity 遇 到 一 个 位 定义 的 引用 时 ， 其 通常 行为 是 输出 这 个 引用 的 了 映像。 比如， 
假设 下 面 的 引用 出 现在 模板 中 的 一 部 分 : 


<input type="text" name="email" value="$email"/> 


当 表 单 初次 装 入 时 ， 变 量 引 用 $email 无 值 ， 你 宁愿 是 一 个 空白 域 而 不 是 具有 
值 "$email"。 使 用 安静 引用 符 可 以 绕 过 Velocity 的 常规 行为 ， 在 VTL 中 不 用 $email 而 
是 用 $lemail 符号 。 所 以 ， 上 面 的 例子 将 会 看 起 来 像 下 面 的 样子 : 


<input type="text" name="email" value="$!email"/> 


现在 ， 当 表单 初次 装 入 时 ，$email 仍然 没有 值 ， 但 是 将 输出 空 字符 囊 而 不 
aw qe 
xÆ "$email" ° 


形式 和 安静 引用 符 可 以 一 起 使 用 ， 如 下 所 示 : 


<input type="text" name="email" value="$! {email}"/> 


11. Case Substitution 


现在 你 大 致 了 解 了 引用 ， 可 以 在 模板 中 使 用 它们 了 。Velocity 采用 了 很 多 JAVA 原理 
的 优点 ， 模 板 设计 人 员 会 发 现 非常 容易 使 用 。 例 如 : 


$foo 


$foo.getBar( ) 


## is 


the same as 


$foo.Bar 


$data. 


## is 


$data. 


$data. 


## is 


$data. 


## is 


getUser("jon") 
the same as 
User("jon") 


getRequest( ) ,getServerName() 
the same as 

Request .ServerName 

the same as 


${data.Request.ServerName} 


这 个 例子 显示 了 引用 的 一 些 其 他 用 法 。Velocity 借鉴 了 Java 的 自省 和 组 件 bean 特 
征 ， 来 解决 引用 名 在 上 下 文中 作为 对 象 和 对 象 方法 的 问题 。 可 以 在 你 的 模板 的 任何 
地 方 插入 引用 和 求 值 。 


Velocity, 建 模 在 Sun Microsystems 定 义 的 BEAN 规 范 之 上 ， 是 大 小 写 敏感 的 ; 开发 
者 努力 捕 扣 和 纠正 可 能 出 现 的 用 户 错误 。 当 方法 getFoo() 在 模板 中 通过 $bar.foo 引 

用 时 ，Velocity 首先 尝试 $getfoo。 如 果 失 败 ， 他 会 再 尝试 $getFoo。 类 似 地 ， 当 一 
个 模板 引用 到 $bar.Foo > Velocity 将 尝试 $getFoo() 先 ， 然 后 尝试 getfoo()。 


注意 : 模板 中 引用 示例 变量 的 问题 仍然 没有 解决 。 只 有 引用 等 价 于 JavaBean 的 
getter/setter 方法 解决 了 。( 比 如 $foo.Name 解决 了 到 类 Foo 的 getName() 示例 方 
法 的 引用 ， 但 不 能 引用 Foo 的 一 个 公共 实例 变量 Name)。 


12. 指令 


因为 指令 (使 用 脚本 来 有 效 操 控 JAVA 代 码 的 输出 ) ALTE eT RIES ET A A 
的 外 观 和 内 容 设 计 ， 引 用 允许 模板 设计 员 为 Web 页 面 产生 动态 内 容 。 


12.1. #set 


#set 指令 用 来 为 引用 设置 相应 的 值 。 值 可 以 被 值 派 给 变量 引用 或 者 是 属性 引 
用 ， 而 且 赋 值 要 在 括号 里 括 起 来 。 


#set( $primate = "monkey" ) 
#set( $customer.Behavior = $primate ) 


赋值 的 左边 必须 是 一 个 变量 应 用 或 者 是 属性 引用 。 右 边 可 以 是 下 面 的 类 型 之 一 : 


变量 引用 
字面 字符 串 
属性 引用 
方法 引用 
字面 数字 
数组 列表 


这 些 例 子 演示 了 上 述 的 每 种 类 型 : 


#set( $monkey = $bill ) ## variable reference 

#set( $monkey.Friend = "monica" ) ## string literal 

#set( $S$monkey.Blame = $whitehouse.Leak ) ## property reference 
#set( $monkey.Plan = $spindoctor.weave($web) ) ## method referen 
ce 

#set( S$monkey.Number = 123 ) ##number literal 

#set( $S$monkey.Say = ["Not", $my, "fault"] ) ## ArrayList 


注意 : 最 后 一 个 例子 中 ， 在 方 括号 [..] 中 定义 的 项 目 可 以 被 ArrayList 类 定义 的 方法 
访问 。 比 如 ， 你 可 以 使 用 $monkey.Say.get(0) 访 问 上 述 的 第 一 个 元 素 。 


右边 也 可 以 是 一 个 简单 的 算术 表达 式 .: 


#set( $value = $foo + 1 ) 
#set( $value = $bar - 1 ) 
#set( $value = $foo * $bar ) 
#set( $value = $foo / $bar ) 


如 果 右 边 是 一 个 属性 或 方法 引用 ， 取 值 是 NULL， 他 将 不 会 赋值 给 左边 。 通 过 这 种 
机 制 将 一 个 存在 的 引用 从 上 下 文中 删除 是 不 可 能 的 。 这 对 Velocity 的 新 手 可 能 会 混 
Ao Pilko : 


#set( $result = $query.criteria("name") ) 
The result of the first query is $result 


#set( $result = $query.criteria("address") ) 


The result of the second query is $result 


如 果 ， $query.criteria("name") 2x 4 ¥ "bill" > 7a $query.criteria("address") 返回 
null > VTL 将 解释 为 : 


The result of the first query is bill 
The result of the second query is bill 


这 往往 会 给 那些 想 构 建 #foreach 循 环 来 试图 通过 属性 和 方法 引用 来 设置 一 个 引用 的 
新 手 带 来 困惑 ， 下 面 马 上 通过 #if 指 令 测 试 一 下 。 例 如 : 


#set( $criteria = ["name", "address"] ) 
#foreach( $criterion in $criteria ) 
#set( $result = $query.criteria($criterion) ) 
#if( $result ) 
Query was successful 
#end 
#end 
在 上 面 的 例子 中 ， 依 靠 $result VAMAR LAW GRA RK RV BK o 4 
$result 被 #set 设 置 后 (添加 到 上 下 文中 )， 他 就 不 能 再 被 设 值 为 null (从 上 下 文中 删 
除 )。 


我 们 对 此 的 解决 方法 是 预 设 $result 为 false。 然 后 如 果 $query.criteria() 调用 失败 ， 
你 就 可 以 检查 之 。 


#set( $criteria = ["name", "address"] ) 
#foreach( $criterion in $criteria ) 


#set( $result 
#set( $result 


false ) 
$query.criteria($criterion) ) 


#if( $result ) 
Query was successful 
#end 


#end 


不 象 其 他 Velocity 444° #set 指令 没有 #end 78 4 © 


12.2. 字面 字符 串 
当 使 用 ##set 指令 时 ， 括 在 双 引 号 中 的 字面 字符 串 将 解析 和 重新 解释 ， 如 下 所 示 : 


#set( $directoryRoot = "www" ) 

#set( $templateName = "index.vm" ) 

#set( $template = "$directoryRoot/$templateName" ) 
$template 


输出 将 会 是 : 


www/index.vm 


然而 ， 当 字面 字符 串 括 在 单 引号 中 时 ， 他 将 不 被 解析 : 


#set( $foo = "bar" ) 
$foo 

#set( $blargh = '$foo' ) 
$blargh 


输出 是 : 


Bar 
$foo 


默认 情况 下 ， 使 用 单 引 号 来 泻 梁 未 解析 文本 在 Velocity 是 有 效 的 。 这 种 特征 可 以 通 
过 编辑 velocity.properties 中 的 stringliterals.interpolate=false 来 改变 。 


12.3. 条 件 


12.3.1 If / Elself / Else 
Velocity 中 的 #if ES ATER DERN > EIFRAA BALE SKK © bite : 


#if( $foo ) 
<strong>Velocity!</strong> 
#end 


变量 $foo ARE’ URCRGA A: ERMPALTA A : (i) $foo 是 一 个 逻辑 变 
BHAA BAK > RA (ii) 值 非 空 。 要 记 住 Velocity 上 下 文 仅 包括 对 象 ， 所 以 当 我 们 
说 “布尔 "boolean' 时 ， 他 会 被 表示 为 “布尔 类 ”(Boolean class)。 这 对 即使 是 返回 布尔 
类 型 的 方法 也 是 申 的 一 自省 架构 将 返回 一 个 具有 相同 逻辑 值 的 布尔 类 。 


do RRB AM > Hif 和 Hend 语句 之 间 的 内 容 将 输出 。 在 这 种 情况 下 ， 如 果 $foo 
为 趴 ， 输 出 将 是 "Velocity!"。 相 反 ， 如 果 $foo 具有 一 个 null 值 ， 或 者 逻辑 假 ， 语 名 
求 值 为 假 ， 则 没有 输出 。 


一 个 #elseif 或 者 #else 项 可 以 用 在 ##f 语 名 中 。 请 注意 ，Velocity 模板 引擎 将 在 第 
一 个 为 真 的 表达 式 时 停止 。 下 面 的 例子 中 ， 假 设 $foo 具有 值 15 而 $bar 等 于 6。 


#if( $foo < 10 ) 
<strong>Go North</strong> 
#elseif( $foo == 10 ) 
<strong>Go East</strong> 
#elseif( $bar == 6 ) 
<strong>Go South</strong> 
#else 
<strong>Go West</strong> 
#end 


在 这 个 例子 中 ，$foo 大 于 10， 所 以 前 面 两 个 比较 失败 。 接 下 来 比较 $bar 和 6， 结 果 
Ai > PE VAT A Go South e 


请 注意 在 现在 ，Velocity 的 数值 比较 约束 为 整 型 一 其 他 类 型 都 将 求 值 为 false。 仅 有 
一 个 例外 是 等 于 '=='， 这 时 Velocity 要 求 等 号 两 边 的 对 象 具有 相同 的 类 型 。 


12.3.2 关系 和 逻辑 操作 符 


Velocity 使 用 等 式 操作 符 来 决定 两 个 变量 间 的 关系 。 这 里 是 一 个 简单 的 例子 演示 如 
何 使 用 等 式 操作 符 : 


#set ($foo 
#Set ($bar 


"deoxyribonucleic acid") 
"ribonucleic acid") 


#if ($foo == $bar) 

In this case it's clear they aren't equivalent. So... 
#else 

They are not equivalent and this will be the output. 
#end 


Velocity 也 具有 逻辑 AND, or 和 NOT 操作 符 。 更 进一步 的 信息 ， 请 E 
VTL Reference Guide 。 下 面 是 一 些 演示 如 何 使 用 逻辑 操作 符 的 例子 


## logical AND 


#if( $foo && $bar ) 
<strong> This AND that</strong> 
#end 


例子 中 #if() 指令 仅 在 $foo 和 $bar +A $ 49 MARA AR Ho te R$foo 为 假 ， 则 表达 式 
也 为 假 ; 并 且 $bar 将 不 被 求 值 。 。 如 果 $foo AŚ > Velocity 模板 引擎 将 继续 检查 
$bar; 的 值 ， 如 果 $bar Aw > MEDRAN A o # H4a This AND that 。 如 果 
$bar 为 假 ， 将 没有 输出 因为 整个 表达 式 为 假 。 


逻辑 OR 的 工作 方式 相同 ， 唯 一 的 例外 是 其 中 一 个 表达 式 要 被 求 值 ， 以 便 决 定 整 个 
表达 式 是 否 为 真 。 请 看 下 面 的 例子 : 


## logical or 


#if( $foo || $bar ) 
<strong>This or That</strong> 
#end 


如 果 $foo AH > Velocity 模板 引擎 就 不 需要 去 察看 $bar 的 值 ， 不 管 $bar 是 否 为 
Bo BAKA AA > Ass E This or That 。 如 果 $foo 为 假 ，$bar 就 必须 检查 
其 值 了 。 在 这 种 情况 下 ， 如 果 $bar 也 是 为 假 ， 表 达 式 将 为 假 ， 没 有 任何 输出 。 雪 
然 ， 如 果 $bar AH > MAARAJA > 4 This or That 。 


对 于 逻辑 NOT 操作 符 ， 只 有 一 个 操作 数 : 


N 


b> as di 


##logical NOT 


#if( !$foo ) 
<strong>NOT that</strong> 
#end 


里 ， 如 果 $foo Aik’ $foo 来 值 为 假 ， 没 有 输出 。 如 果 $foo 为 假 ，!$foo 求 值 为 
> 输出 NOT that 。 请 当心 ， 不 要 和 安静 引用 quiet reference $!foo 混淆 它们 是 完 
不 同 的 。 


12.4. 循环 


12.4.1. Foreach 循环 


#foreach 元 素 允 许 进行 循环 ， 例 如 : 


<ul> 

#foreach( $product in $allProducts ) 
<li>$product</1li> 

#end 

</ul> 


à foreach 循环 将 导致 $allProducts 列表 (对 象 ) 为 查询 所 有 的 产品 $products (8 
标 ) 遍 历 一 遍 。 每 次 经 过 循环 ， 从 $allProducts 取 得 的 值 将 置 于 $product 变量 之 中 。 


$allProducts 变量 的 内 容 是 一 个 矢量 ， 一 个 哈 希 表 或 者 数组 。 赋 给 $product 变量 的 
值 是 一 个 Java 对 象 并 且 可 以 从 一 个 类 似 的 变量 引用 。 例 如 ， 如 果 $product $ &— 
个 Java 的 产品 类 ， 其 名 称 可 以 通过 引用 $product.Name 方法 来 检索 ( 即 : 
$Product.getName()) ° 


我 们 假定 $allProducts 是 一 个 哈 希 表 。 如 果 你 想 检 索 关 键 字 的 值 或 者 在 哈 希 表 中 的 
对 象 ， 你 可 以 使 用 以 下 的 代码 : 


<ul> 
#foreach( $key in $allProducts.keySet() ) 
<li>Key: $key -> Value: $allProducts.get($key)</1li> 
#end 
</ul> 


Velocity 提供 一 个 更 容易 的 方式 或 的 循环 计数 ， 以 便 你 可 以 做 下 面 类 似 的 工作 : 


<table> 

#foreach( $customer in $customerList ) 
<tr><td>$velocityCount</td><td>$customer .Name</td></tr> 

#end 

</table> 


循环 计数 变量 的 缺 省 名 称 是 $velocityCount， 在 velocity.properties 配置 文件 中 标 
明 。 黑 认 情 况 下 ， 该 变量 从 1 开始 计数 ， 但 是 可 以 在 velocity.properties 文件 中 设 为 
从 0 或 者 1 开始 。 下 面 是 velocity.properties 文件 中 循环 变量 设置 一 节 : 


# Default name of the loop counter 
# variable reference. 
directive.foreach.counter.name = velocityCount 


# Default starting value of the loop 
# counter variable reference. 
directive. foreach.counter.initial.value = 1 


12.5. 包含 


#include 脚本 元 素 允 许 模 板 设 计 人 员 和 包含 〈 导 入 ) 本 地 文件 ， 这 个 文件 将 插入 到 
#include 指令 被 定义 的 地 方 。 文 件 的 内 容 并 不 通过 模板 引擎 来 泻 染 。 处 于 安全 的 原 
， 被 包含 的 文件 只 可 以 放 在 TEMPLATE_ROOT 下 。 


#include( "one.txt" ) 
#include 指令 引用 的 文件 在 双 引 号 内 。 如 果 超 过 一 个 文件 ， 其 间 用 过 号 隔 开 。 


#include( "one.gif", "two.txt", "three.htm" ) 


被 包含 的 文件 并 不 是 一 定 要 用 文件 名 来 引用 ， 事 实 上 ， 最 好 的 办 法 是 使 用 变量 而 不 
是 文件 名 。 这 在 根据 规则 决定 何 时 提交 页 面 时 ， 决 定 目 标 输出 是 很 有 用 的 。 


#include( "greetings.txt", $seasonalstock ) 


12.6. 解析 


#parse 脚本 元 素 允 许 页 面 设计 员 导 入 包含 VTL 的 本 地 文件 。 Velocity 将 解析 和 泻 染 
g E 的 模板 。 


#parse( "me.vm" ) 


wR #include 44 > Hparse 可 以 使 用 变量 而 不 是 一 个 实在 的 模板 文件 。#parse 引 
用 的 模板 文件 必须 包含 的 TEMPLATE_ROOT 指 定 的 目录 之 下 。 和 扩 nclude 指令 不 
一 样 ，#parse 只 有 一 个 参数 。 


VTL 模板 templates can have #parse statements referring to templates that in turn 
have #parse statements. By default set to 10, the parse_directive.maxdepth line of 
the velocity.properties allows users to customize maximum number of #parse 
referrals that can occur from a single template. (Note: If the 
parse_directive.maxdepth property is absent from the velocity.properties file, 
Velocity will set this default to 10.) Recursion is permitted, for example, if the 
template dofoo.vm contains the following lines: 


Count down. 

#set( $count = 8 ) 
#parse( "parsefoo.vm" ) 
All done with dofoo.vm! 


It would reference the template parsefoo.vm, which might contain the following 
VTL: 


$count 
#set( $count = $count - 1 ) 
#if( $count > 0 ) 

#parse( "parsefoo.vm" ) 
#else 

All done with parsefoo.vm! 
#end 


After "Count down." is displayed, Velocity passes through parsefoo.vm, counting 
down from 8. When the count reaches 0, it will display the "All done with 
parsefoo.vm!" message. At this point, Velocity will return to dofoo.vm and output 
the "All done with dofoo.vm!" message. 


12.7. 停止 
Hstop 脚本 允许 模板 设计 员 停止 模板 引擎 的 执行 ， 并 返回 。 这 通常 用 作 调试 。 


#stop 


12.10. x 


#macro 脚本 元 素 允 许 模 板 设计 者 在 VTL 模板 中 定义 重复 的 段 。Velocimacros * © 
是 在 复杂 还 是 简单 的 场合 都 非常 有 用 。 下 面 这 个 Velocimacro， 仅 用 来 节省 击 键 和 
减少 排版 错误 ， 介 绍 了 一 些 Velocity 宏 的 概念 。 


#macro( d ) 
<tr><td></td></tr> 
#end 


在 例子 中 ，Velocimacro 定 义 为 d， 它 可 以 象 调用 其 他 VTL 指 令 一 样 的 形式 来 进行 调 
用 : 


#d ( ) 


当 这 个 模板 被 调用 时 ，Velocity 将 #d() 替换 为 一 个 单行 的 空 表格 。 


Velocimacro 可 以 带 一 些 和 参数 ， 也 可 以 不 带 参 数 (如 上 例 所 示 ) 。 但 在 他 被 调用 
时 ， 所 带 的 参数 必须 和 其 定义 时 的 参数 一 样 。 很 多 Velocimacros 定义 为 不 止 一 个 参 
数 。 下 面 这 个 宏 带 有 两 个 参数 ， 一 个 颜色 ， 一 个 数组 。 


#macro( tablerows $color $somelist ) 
#foreach( $something in $somelist ) 
<tr><td bgcolor=$color>$something</td></tr> 
#end 
#end 


在 这 个 例子 中 定义 的 Velocimacro， 名 为 tablerows, 要 求 两 个 参数 。 第 一 个 参数 代替 
$color, 第 二 个 代替 $somelist 。 


可 以 写 进 VTL 模板 中 的 东西 都 可 以 写 进 Velocimacro 的 主体 部 分 。tablerows 宏 其 实 
是 一 个 foreach 74 4] ° ##tablerows 宏 的 定义 中 有 两 个 #ende 语 名 ， 第 一 个 属于 
#foreach, 第 二 个 结 来 宏 定 义 。 


#set( $greatlakes = ["Superior", "Michigan", "Huron", "Erie", "Ontar 


io"] ) 
#set( $color = "blue" ) 
<table> 
#tablerows( $color $greatlakes ) 
</table> 


请 注意 $greatlakes #4% T $somelist ° 24% > SH#tablerows 宏 被 调用 时 ， 将 产生 以 
下 输出 : 


<table> 
<tr><td bgcolor="blue">Superior</td></tr> 
<tr><td bgcolor="blue">Michigan</td></tr> 
<tr><td bgcolor="blue">Huron</td></tr> 
<tr><td bgcolor="blue">Erie</td></tr> 
<tr><td bgcolor="blue">Ontario</td></tr> 
</table> 


Velocimacros 在 Velocity 模板 语句 内 定义 ， 这 意味 着 它 在 同一 站 点 内 的 其 他 Velocity 
模板 中 并 不 有 效 。 定 义 一 个 宏 ， 并 使 其 与 其 他 模板 共享 很 具有 明显 的 优点 : 他 减少 
了 在 大 量 的 模板 内 重复 定义 宏 的 工作 ， 并 减少 了 出 错 的 机 会 ， 并 确保 对 其 他 宏 的 改 
变 对 其 他 所 有 模板 有 效 。 


但 如 果 #tablerows($color $list) 宏 是 在 一 个 Velocimacros 模板 库 内 定义 的 ， 它 就 可 
以 被 其 他 常规 模板 所 用 。 当 然 ， 它 可 以 用 于 各 种 目的 ， 也 可 重用 多 次 。 在 表示 所 有 


Hig’ & (fungi) 的 mushroom.vm 724k P > #Htablerows Æ T ARA KA) EAA hy 


o 


F 


#set( $parts = ["volva", "stipe", "annulus", "gills","pileus"] ) 
#set( $cellbgcol = "#CCOOFF" ) 

<table> 

#tablerows( $cellbgcol $parts ) 

</table> 


我 们 对 mushroom.vm 执 行 请 求 ，Velocity 将 在 模板 库 内 找到 #tablerows K (在 
velocity.properties 文件 中 定义 ) 并 产生 以 下 输出 : 


<table> 
<tr><td bgcolor="#CCOOFF">volva</td></tr> 
<tr><td bgcolor="#CCOOFF">stipe</td></tr> 
<tr><td bgcolor="#CCOOFF">annulus</td></tr> 
<tr><td bgcolor="#CCOOFF">gills</td></tr> 
<tr><td bgcolor="#CCOOFF">pileus</td></tr> 
</table> 


12.10.1. Velocimacro 参数 
Velocimacros 的 参数 可 以 是 以 下 的 VTL 元 素 : 


引用 (Reference) : 以 '$' 打头 的 元 素 

字面 字符 串 (String literal) : 比如 "$foo" 或 ‘hello’ 
字面 数字 : 1, 2 .... 

整数 范围 : [ 1..2] 或 [$foo .. $bar] 

对 象 数 组 : [ "a", "b", "ce" 


布尔 假 


当 把 引用 作为 参数 传递 给 Velocimacros 时 ， 请 注意 引用 是 按 “ 名 字 ” 传 递 的 。 这 意味 
着 他 们 的 值 在 每 次 使 用 他 们 的 Velocimacro 中 产生 。 这 个 特性 允许 你 在 方法 调用 是 
传递 引用 ， 并 在 每 次 使 用 时 进行 方法 调用 。 例 如 ，Fo， 当 调用 下 面 的 Velocimacro 
时 ， 


#macro( callme $a ) 
$a $a $a 
#end 


#callme( $foo.bar() ) 


结果 是 ， 在 方法 bar() 中 ， 引 用 $foo 被 调用 了 3 次 。 


咋 看 时 ， 这 个 特征 让 人 吃惊 ， 当 当 你 考虑 一 下 Velocimacros 的 原本 动机 一 在 VTL 模 
板 中 避免 很 多 " 剪 切 复制 "操作 一 你 就 会 明白 。 它 允许 你 将 无 状态 对 象 ， 比 如 在 一 个 
颜色 表格 行内 重复 产生 一 些 颜 色 次 序 的 对 象 ， 传 递 给 Velocimacro。 

如 果 你 需要 使 用 这 个 特征 ， 你 通常 可 以 从 方法 内 取得 一 个 值 ， 作 为 一 个 新 的 引用 传 
递 给 宏 : 


#set( $myval = $foo.bar() ) 
#callme( $myval ) 


12.10.2. Velocimacro 属性 


在 velocity.properties 文件 中 有 数 行 定义 可 以 用 来 灵活 实现 Velocimacros。 详 细 情 况 
请 参见 开发 指南 (Developer Guide) ° 


velocimacro.library 一 是 一 个 过 号 分 隔 的 所 有 Velocimacro 模板 库 的 列表 。 默 认 情 况 
TF > Velocity 搜寻 一 个 单一 的 库 VM_global_library.vm.。 预 先 配置 的 模板 路 径 用 来 
查找 Velocimacro 库 。 


velocimacro.permissions.allow.inline 一 这 个 属性 决定 Velocimacros 是 否 可 以 在 常规 
模板 内 定义 ， 取 值 为 逻辑 True 或 者 False。 默 认 情 况 下 ， 设 置 为 true， 允 许 设计 者 在 
产 规模 板 内 定义 宏 。 


velocimacro.permissions.allow.inline.to.replace.global -Æ true 或 者 false， 允 许 
标明 是 否 人 允许 在 常规 模板 内 定义 的 Velocimacro 代 替 在 模板 库 中 定义 并 通过 
velocimacro.library 属 性 在 启动 时 装 入 的 全 局 宏 。 默 认 设置 为 false 。 


velocimacro.permissions.allow.inline.local.scope -逻辑 true 或 者 false， 默 认 值 为 
false。 控 制 是否 在 模板 内 定义 的 Velocimacros 仅 在 定义 它 的 模板 内 可 见 。 换 名 话 

说 ， 如 果 设 置 为 true， 一 个 模板 可 以 定义 仅 能 被 他 所 用 的 宏 。 你 可 以 用 它 来 做 一 些 
漂亮 的 宏 ， 如 果 一 个 全 局 调用 另 一 个 全 局 宏 ， 在 局 部 (inline) 范围 内 ， 当 被 一 个 模 
板 调 用 时 ， 该 模板 可 以 定义 一 个 被 第 一 个 全 局 宏 调用 的 第 二 个 全 局 宏 的 私有 实现 。 
其 他 所 有 模板 都 不 受 影响 。 


velocimacro.context.localscope -逻辑 值 true 或 者 false， 缺 省 值 为 false。 但 设置 为 
true 时 ， 所 有 在 Velocimacro 内 通过 #set() 进行 的 修改 都 将 被 视 为 Velocimacro 的 本 
地 行为 ， 不 会 影响 到 其 上 下 文 。 


velocimacro.library.autoreload 一 此 属性 控制 Velocimacro 库 的 自动 载 入 。 缺 省 值 为 

false。 如 果 设 置 为 true， 被 调用 的 Velocimacro 得 源 库 将 被 检查 是 否 改变 ， 并 在 必要 
是 重新 载 入 。 这 将 使 你 可 以 改变 和 测试 Velocimacro 库 ， 而 不 必 重 新 局 动 应 用 服务 

器 或 者 servlet 容 器 ， 就 象 你 工作 在 常规 模板 一 样 。 这 个 模 时 仅 在 资源 载 入 器 的 缓存 

模 时 被 关闭 的 情况 下 有 效 (4efile.resource.loader.cache = false )。 此 特征 为 开发 时 

设计 ， 不 要 在 生产 模式 时 使 用 。 


12.10.3. Velocimacro Trivia 


4 ay > Velocimacros 在 其 首次 在 模版 中 使 用 前 必须 首先 定义 它 。 这 意味 着 ， 
#macro() 宣称 应 该 在 使 用 Velocimacros 之 前 。 


如 果 你 想 #parse() 一 个 包含 #macro() 指令 的 模板 ， 记 住 这 个 非常 重要 。 因 为 
#parse() 在 运行 时 发 生 ， 解 析 器 在 解析 时 要 决定 是 否 模版 中 一 个 看 起 来 像 VM 的 元 
素 真 是 VM， 所 以 解析 一 系列 VM 宣称 可 能 并 不 能 如 愿 地 工作 的 很 好 。 为 避免 如 此 ， 
可 以 简单 地 使 用 velocimacro.library 的 办 法 ， 使 Velocity 在 尼 动 时 载 入 VM © 


13. Getting literal 


Velocity 使 用 特殊 字符 $ 和 # 来 帮助 它 工 作 ， 所 以 如 果 要 在 template 里 使 用 这 些 特 殊 字 
符 要 格外 小 心 。 本 节 将 讨论 $ 字 符 。 


13.1. 货币 字符 


这 是 没有 问题 的 : "| bought a 4 Ib. sack of potatoes at the farmer's market for only 
$2.50!"，VTL 中 使 用 $2.5 这 样 的 货币 标识 是 没有 问题 得 的 ，VTL 不 会 将 它 错 认为 是 
一 个 reference， 因 为 VTL 中 的 reference 总 是 以 一 个 大 写 或 者 小 写 的 字母 开始 。 


13.2. 转 义 有 效 的 VIL 指令 


某 些 情况 使 用 Velocity 可 能 会 觉得 很 烦恼 。 逃 避 特 殊 符 是 处 理 出 现在 你 的 模板 中 VTL 
特殊 符 有 效 方法 ， 就 是 使 用 反 斜 杠 (“\”)。 


#set( $email = "foo" ) 
$email 


假如 Velocity 在 你 的 模板 中 遇 到 $email， 它 会 搜索 上 下 文 ， 得 到 相应 的 值 。 这 里 的 输 
出 是 foo， 因 为 $email 被 定义 了 。 假 如 $email 没 有 被 定义 ， 输 出 会 是 $email。 


设想 $email 被 定义 了 (例如 ， 它 的 值 是 foo)， 而 且 你 想 输出 $email。 这 里 有 几 种 方法 
能 达到 目的 ， 但 是 最 简单 的 是 使 用 逃避 符 。 


## The following line defines $email in this template: 
#set( $email = "foo" ) 

$email 

\$email 


$email 


REAVER T ELGG o REUN > (RAGemail E7 A \$email © 那些 例子 
5 $email t A € LH X © 


$email 
\$email 
\\$email 
\\\$email 


将 显示 为 : 


$email 
\$email 
\\$email 
\\\$email 


\\$email\\\$email 


注意 Velocity 处 理 定义 了 的 references 与 没有 定义 的 不 一 样 。 这 里 set$foo 的 值 为 
gibbous ° 


#set( $foo = "gibbous" ) 
$moon = $foo 


输出 会 是 : $moon=gibbous,$moon 按照 字面 上 输出 因为 它 没 有 定义 ，gibbous 替 
代 $foo 输 出 。 避 开 VTL 的 directives 还 有 其 他 方法 ， 在 Directives 那 章节 会 更 详细 描 


13.3. 转 义 无 效 的 VTL 指令 


VTL T vst & HL ("/") KAT 4 L > directives can be escaped with the 
backslash character in a manner similar to valid VTL references. 


## #include( "a.txt" ) renders as <contents of a.txt> 
#include( "a.txt" ) 


## /#include( "a.txt" ) renders as /#include( "a.txt" ) 
/#include( "a.txt" ) 


## //#include ( "a.txt" ) renders as /<contents of a.txt> 
//#include ( "a.txt" ) 


在 转 义 在 一 个 单一 指令 内 包含 多 个 脚本 元 素 ( 比如 f-else-end 语 句 ) 的 指令 时 应 多 
加 小 心 。 下 面 是 一 个 典型 的 VTL if 语 名 ; 


#if( $jazz ) 
Vyacheslav Ganelin 
#end 


如 果 $jazz 为 true， 输 出 是 


Vyacheslav Ganelin 


如 果 $jazz 为 false， 将 没有 输出 。 转 义 脚本 元 素 将 改变 输出 。 考 虑 下 面 的 情况 ; 


/#if( $jazz ) 
Vyacheslav Ganelin 
/#end 


Ke $jazz ZARB > i BARE 


#if($ jazz ) 
Vyacheslav Ganelin 
#end 


事实 上 ， 因 为 所 有 脚本 元 素 都 被 转 义 了 ， $jazz 永远 不 会 被 求 值 。 将 设 反 斜 杠 在 被 
合法 转 义 的 脚本 元 素 之 前 


//#if( $jazz ) 
Vyacheslav Ganelin 
//#end 


这 时 ， 如 果 $jazz AA > Hh xe 


/ Vyacheslav Ganelin 
/ 


为 理解 这 个 情况 ， 请 注意 在 一 个 新 行 结束 是 将 在 输出 中 忽略 新 的 一 行 。 因 此 ， 经 过 
#if() 前 的 /1 加 工 后 ， 拓 f() 块 紧 跟 第 一 个 1/。 最 后 一 个 /位 于 新 的 一 行 ， 因 为 
在 'Ganelin' 后 又 一 个 新 行 ， 所 以 ， 最 后 的 那个 位 于 #end 之 前 的 // 是 语句 块 的 一 部 


分 。 


如 果 $jazz 为 false， 这 里 将 没有 输出 。 注 意 ， 在 开始 破坏 了 if 语句 的 情况 将 不 能 被 
正确 转 义 : 


///#if( $jazz ) 
Vyacheslave Ganelin 
//#end 


E> Hif 被 转 义 ， 但 有 一 个 #end 被 保留 了 ; 所 以 有 多 个 结束 语句 将 导致 解析 错 


`o 
TR ° 


14. VTL 格式 化 问题 
虽然 在 本 指南 中 的 VTL 经 常 显 示 在 新 行 中 或 者 有 空格 ， 但 是 下 面 的 VTL 


#set( $imperial = ["Munetaka", "Koreyasu", "Hisakira","Morikune"] 
) 
#foreach( $shogun in $imperial ) 
$shogun 
#end 


和 下 面 的 写法 同样 有 效 。 


Send me #set($foo = ["$10 and ","a cake"])#foreach($a in $foo)$a 
#end please. 


Velocity 的 行为 并 不 受 空格 的 影响 ， 前 述 的 指令 也 可 以 写成 : 


Send me 

#set( $foo = ["$10 and ","a cake"] ) 
#foreach( $a in $foo ) 

$a 

#end 

please. 


或 者 


Send me 
#set($foo = ["$10 and ","a cake"]) 
#foreach ($a in $foo )$a 
#end please. 


上 面 每 种 写法 结果 都 一 样 。 


15. 其 它 特 征 和 杂项 


15.1. 数学 特征 


Velocity 有 一 的 数学 功能 ， 可 以 使 用 Set 指令 用 在 模版 中 。 下 面 的 共识 分 别 演 
示 了 加 减 乘除 运 


#set( $foo = $bar + 3 ) 
#set( $foo = $bar - 4 ) 
#set( $foo = $bar * 6 ) 
#set( $foo = $bar / 2 ) 


= 5k 


当 进 行 除法 运算 时 ， 结 果 将 会 是 整数 。 e When a division operation is performed, the 
result will be an nteger 余数 则 可 以 通过 模 (%) 运 算 获 得 。 


#set( $foo = $bar % 5 ) 


在 Velocity 中 ， 只 有 整数 可 以 进行 数学 运算 ; 如 果 执 行 非 整数 的 数学 运算 ， 将 被 记 
录 下 来 ， 并 返 null o 


15.2. 范围 操作 符 


范围 操作 符 可 以 和 #set 和 大 foreach 语句 一 起 使 用 。 有 助 于 产生 一 个 整数 的 目标 数 
组 ， 范 围 操作 符 有 以 下 的 结构 : 


[n..m] 


n 和 m 都 必须 是 整数 或 者 可 以 产生 整数 。 不 管 m 大 于 或 者 小 于 n 都 没关系 ; 在 m 小 
于 n 这 种 情况 下 ， 范 围 可 以 向 下 计数 。 下 面 是 使 用 范围 操作 符 的 例子 : 


Sa — Sa F- 


#foreach( $foo in [1..5] ) 
$foo 
#end 


第 二 个 例子 


#foreach( $bar in [2..-2] ) 
$bar 
#end 


第 三 个 例子 


#set( $arr = [0..1] ) 
#foreach( $i in $arr ) 
$i 

#end 


第 四 个 例子 


[1..3] 


他 们 分 别 产生 一 下 输出 


[1..3] 


范围 操作 符 和 #set 和 #foreach 指令 一 起 使 用 时 ， 只 是 产生 数组 。 


页 面 设 计 人 员 在 设计 具有 相同 尺寸 的 表格 时 ， 有 时 没有 足够 的 数据 来 填充 ， 他 们 会 
发 现 范围 操作 符 非 常 有 用 。 


15.3. 进 阶 : 转 义 和 |! 


当 一 个 引用 被 ! 字符 处 于 静寂 模式 ， 并 且 ! 字符 在 转 义 符 / 前 出 现 ， 应 用 将 用 一 种 特 
别 的 方式 处 理 。 请 注意 他 和 常规 转 义 的 不 同 ， 下 面 这 种 情况 / 先 于 ! 出 现 : 


#set( $foo = "bar" ) 
$/!foo 

$/! {foo} 

$//!f00 

$///!foo 


这 样 将 被 加 工 成 


$!foo 

$! {foo} 
$/!foo 
$//!foo 


对 比 常规 转 义 ，/ 先 于 $: 


/$foo 
/$! foo 
/$! {Foo} 
//$\ {foo} 


15.4. Velocimacro #12 

本 节 是 关于 Velocimacros 的 一 个 小 型 FAQ。 本 届 内 容 会 不 时 更 新 ， 所 以 请 常 来 检查 
新 的 内 容 ， 

注 : 本 节 中 ，'Velocimacro' 将 简写 为 VM'。 


Q: 是 否 可 以 使 用 指令 directive 或 者 VM 作为 另 一 个 VM 的 参数 ? 例如 : #center( 
#bold("hello") ) 


A: 不 行 。 指 令 不 能 用 作 指 令 的 参数 ， 而 大 多 数 情况 下 ， 作 为 实际 的 应 用 ，VM 就 是 
指令 。 


不 过 也 有 一 些 办 法 。 一 个 简单 的 做 法 是 使 用 双 引 号 来 加 工 你 的 内 容 。 所 以 ， 你 可 以 


这 样 : 


#set($stuff = "#bold('hello')" ) 
#center( $stuff ) 


甚至 可 以 节省 一 个 步骤 : 


#center( "#bold( 'hello' )" ) 


请 注意 ， 后 面 这 个 例子 中 ， 参 数 是 在 VM 内 部 被 求 值 ， 不 是 在 调用 的 那 一 层次 上 。 
换 名 话说， 被 传 入 的 VM 的 参数 是 整个 被 传 入 的 ， 并 且 在 传 入 的 VM 内 部 被 求 值 。 所 
以 我 们 可 以 这 样 做 : 


#macro( inner $foo ) 
inner : $foo 
#end 


#macro( outer $foo ) 
#set($bar = "outerlala") 
outer : $foo 

#end 

#set($bar = 'calltimelala' ) 

#outer( "#inner($bar)" ) 


这 里 ， 输 入 将 会 是 : 


Outer : inner : outerlala 


A"#inner($bar)" 的 求 值 发 生 在 #outer() 内 部 ， 所 以 在 #outer() 内 设置 的 $bar 得 值 
会 是 其 使 用 的 值 。 


这 是 一 个 有 意 的 保护 特征 一 参数 按 名 称 传 递 给 VM， 所 以 可 以 将 象 状态 引用 的 东西 
传 给 VM ， 比 如 : 


#macro( foo $color ) 
<tr bgcolor=$color><td>Hi</td></tr> 
<tr bgcolor=$color><td>There</td></tr> 
#end 


#foo( $bar.rowColor() ) 


rowColor() 被 重复 调用 而 不 是 一 次 。 为 避免 如 此 ， 可 以 调用 VM 外 部 的 方法 ， 然 后 
将 值 传 递 给 VM. 


#set($color = $bar.rowColor()) 
#foo( $color ) 


Q: 是 否 可 以 通过 #parse() 注 册 VM ? 

A: f> Velocimacros 在 其 首次 在 模版 中 使 用 前 必须 首先 定义 它 。 这 意味 着 ， 
#macro() 宣称 应 该 在 使 用 Velocimacros 之 前 。 

如 果 你 想 #parse() 一 个 包含 #macro() 指令 的 模板 ， 记 住 这 个 非常 重要 。 因 为 
#parse() 在 运行 时 发 生 ， 解 析 器 在 解析 时 要 决定 是 否 模版 中 一 个 看 起 来 像 VM 的 元 
素 监 是 VM， 所 以 解析 一 系列 VM 宣称 可 能 并 不 能 如 愿 地 工作 的 很 好 。 为 避免 如 此 ， 
可 以 简单 地 使 用 velocimacro.library 的 办 法 ， 使 Velocity 在 尼 动 时 载 入 VM © 


Q. 什么 是 VM 自动 载 入 (Velocimacro Autoreloading) ? 
A. 这 是 一 个 属性 ， 在 开发 时 使 用 ， 而 不 时 运行 时 : 


velocimacro.library.autoreload 


默认 值 为 false。 当 设置 为 true 时 ， 连 同 <type>.resource.loader.cache 属性 设置 为 
false (这 里 是 使 用 的 资源 载 入 器 的 名 称 ， 比 如 file) > Velocity 引擎 在 你 创建 VM 库 
文件 是 将 自动 载 入 其 改变 ， 这 样 你 就 不 必 将 其 导入 servlet 引擎 (或 者 应 用 程序 ) 

中 ， 或 者 用 其 他 手段 来 使 其 自动 重新 载 入 。 


下 面 是 一 个 简单 的 设置 配置 组 合 : 
file.resource.loader.path = templates 


file.resource.loader.cache = false 
velocimacro.library.autoreload = true 


注意 在 生产 状态 (运行 时 ) 不 要 使 其 打开 。 


15.5. 字符 串联 
开发 者 常 问 的 一 个 问题 是 “我 如 何 进行 字符 串 串 联 ? ?是 否 有 类 似 于 JAVA 中 的 '+' 操 作 
符 ? 


为 了 串联 VTL 中 的 引用 ， 你 不 得 不 将 它们 “ 放 在 一 起 "。 而 你 想 要 放置 在 一 起 的 上 下 
文 很 重要 ， 下 面 举例 说 明 。 


在 常规 " 策 办 法 "模板 中 : 


#set( $size 
#set( $name 


"Big" ) 
"Ben" ) 


The clock is $size$name. 


输出 将 会 是 : The clock is BigBen'。 我 们 来 看 更 有 趣 的 事情 ， 比 如 ， 当 你 想 串 联 一 
个 字符 串 并 传递 给 一 个 方法 ， 或 者 设置 一 个 新 的 引用 ， 可 以 这 样 : 


#set( $size = "Big" ) 
#set( $name = "Ben" ) 
#set($clock = "$size$name" ) 


The clock is $clock. 


结果 是 一 样 的 。 作 为 最 后 一 个 例子 ， 当 你 想 混合 “静态 "字符 囊 到 引用 中 ， 你 可 能 需 
要 使 用 "形式 引用 ”: 

#set( $size = "Big" ) 

#set( $name = "Ben" ) 


#set ($clock "${size}Tall$name" ) 


现在 ， 输 出 将 会 是 The clock is BigTallBen' ° 
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基本 工具 [Basic utilities] 


让 使 用 Java 语 言 变 得 更 舒适 


1.1 使 用 和 避免 null : W ee 会 引起 令 人 困 RENE > 有些 时 候 它 让 人 
很 不 舒服 。 很 多 Guava 工 具 类 用 快速 失败 拒绝 null 值 ， 而 不 是 盲目 地 接受 


1.2 前 置 条 件 : 让 方法 中 的 条 件 检 查 更 简单 

1.3 常见 Object 方 法 : 简化 Object 方 法 实现 ， 如 hashCode() 和 toString() 
1.4 HEAR: Guava 强 大 的 ”流畅 风格 比较 器 ” 

1.5 Throwables : 简化 了 异常 和 错误 的 传播 与 检查 


2. 集合 [Collections] 


Guava 对 JDK 集 合 的 扩展 ， 这 是 Guava 最 成 熟 和 为 人 所 知 的 部 分 
2.1 不 可 变焦 合 : 用 不 变 的 集合 进行 防御 性 编程 和 性 能 提升 。 


2.2 新 集合 类 型 : multisets, multimaps, tables, bidirectional maps 
2.3 强大 的 集合 工具 类 : 提供 java.util.Collections 中 没有 的 集合 工具 


2.4 扩展 工具 类 : 让 实现 和 扩展 集合 类 变 得 更 容易 ， 比 如 创建 Collection 的 装饰 
器 ， 或 实现 迭代 器 


3. 缓行 [Caches] 


Guava Cache : 本 地 缓存 实现 ， 支 持 多 种 缓存 过 期 策略 
4. 马 效 式 风格 [Functional idioms] 
Guava 的 函数 式 支持 可 以 显著 简化 代码 ， 但 请 说 惯 使 用 它 
5. 并 发 [Concurrency] 


强大 而 简单 的 抽象 ， 让 编写 正确 的 并 发 代码 更 简单 
5.1 ListenableFuture : 完成 后 触发 回调 的 Future 
5.2 Service 框 架 : 抽象 可 开启 和 关闭 的 服务 ， 帮 助 你 维护 服务 的 状态 逻辑 


6. 字符 串 处 理 [Strings] 

非常 有 用 的 字符 串 工 具 ， 包 括 分 割 、 连 接 、 填 充 等 操作 

7. 2 Æ Žž # [Primitives] 

扩展 IDK 未 提供 的 原生 类 型 (如 int、char) 操作 ， 包 括 某 些 类 型 的 无 符号 形式 
8. È |x| [Ranges] 

可 比较 类 型 的 区 间 API， 包 括 连续 和 离散 类 型 

9.1/0 


简化 MO 尤其 是 IO 流 和 文件 的 操作 ， 针 对 Java5 和 6 版 本 


10. 放 列 [Hash] 


提供 比 Object.hashCode() 更 复杂 的 散 列 实现 ， 并 提供 布 鲁 姆 过 滤器 的 实现 
11. 事件 总 线 [EventBus] 

发 布 -订阅 模式 的 组 件 通 信 ， 但 组 件 不 需要 显 式 地 注册 到 其 他 组 件 中 

12. 效 学 运算 [Math] 

优化 的 、 充 分 测试 的 数学 工具 类 


13. 反射 [Reflection] 


Guava 的 Java 反射 机 制 工具 类 


1- 基 本 工具 


1.1- 使 用 和 避免 null 


原文 链接 译文 链接 译 者 : 沈 义 扬 
Doug Lea Ù > “Null ABH ° ” 
4 Sir C. A. R. Hoare 使 用 了 Pu 引用 后 说 ，?* 使 用 它 导 致 了 十 亿美 金 的 错误 。” 


轻率 地 使 用 null 可 能 会 导致 很 多 令 人 惊 眉 的 问题 。 通 过 学 习 Google 底 层 代 码 库 ， 我 
们 发 现 95% 的 集合 类 不 接受 null 值 作为 元 素 。 我 们 认为 ， 相 比 默默 地 接受 null， 使 用 
快速 失败 操作 拒绝 null 值 对 开发 者 更 有 帮助 。 


此 外 ，Null 的 含糊 语义 让 人 很 不 舒服 。Null 很 少 可 以 明确 地 表示 某 种 语义 ， 例 如 ， 
Map.get(key) 返 回 Null 时 ， 可 能 表示 map 中 的 值 是 null， 亦 或 map 中 没有 key 对 应 的 
值 。Null 可 以 表示 失败 、 成 功 或 几乎 任何 情况 。 使 用 Null 尺 外 的 特定 值 ， 会 让 你 的 
逻辑 描述 变 得 更 清晰 。 


Null 确 实 也 有 合适 和 正确 的 使 用 场景 ， 如 在 性 能 和 速度 方面 Null 是 廉价 的 ， 而 且 在 
对 象 数组 中 ， 出 现 Null 也 是 无 法 避免 的 。 但 相对 于 底层 库 来 说 ， 在 应 用 级 别 的 代码 
中 ，Null 往 往 是 导致 混乱 ， 疑 难 问题 和 模糊 语义 的 元 凶 ， 就 如 同 我 们 举 过 的 
Map.get(key) 的 例子 。 最 关键 的 是 ，Null 本 身 没有 定义 它 表达 的 意思 。 


鉴于 这 些 原因 ， 很 多 Guava 工 具 类 对 Null 值 都 采用 快速 失败 操作 ， 除 非 工具 类 本 身 
提供 了 针对 Null 值 的 因 变 措施 。 此 外 ，Guava 还 提供 了 很 多 工具 类 ， 让 你 更 方便 地 
用 特定 值 替换 Null 值 。 


有 具体 案例 


不 要 在 Set 中 使 用 null， 或 者 把 null 作 为 map 的 键 值 。 使 用 特殊 值 代表 null 会 让 查找 操 
作 的 语义 更 清晰 。 


如 果 你 想 把 null 作 为 map 中 某 条 目的 值 ， 更 好 的 办 法 是 不 把 这 一 条 目 放 到 map 中 ， 
而 是 单独 维护 一 个 " 值 为 null 的 键 集合 ” (null keys)。Map 中 对 应 茶 个 键 的 值 是 null ， 
和 map 中 没有 对 应 茶 个 键 的 值 ， 是 非常 容易 混淆 的 两 种 情况 。 因 此 ， 最 好 把 值 为 
null 的 键 分 离开 ， 并 且 和 仔细 想 想 ，null 值 的 键 在 你 的 项 目 中 到 底 表 达 了 什么 语义 。 


如 果 你 需要 在 列表 中 使 用 null 并 且 这 个 列表 的 数据 是 稀 跤 的， 使 用 
Map<lnteger E> 可 能 会 更 高 效 ， 并 且 更 准确 地 符合 你 的 潜在 需求 。 


此 外 ， 考 虑 一 下 使 用 自然 的 null 对 象 一 一 特殊 值 。 举 例 来 说 ， 为 某 个 enum 类 型 增加 
特殊 的 枚 举 值 表 示 null， 比 如 java.math.RoundingMode 就 定义 了 一 个 枚 举 值 
UNNECESSARY， 它 表示 一 种 不 做 任何 舍 入 操作 的 模式 ， 用 这 种 模式 做 使 入 操作 
会 直接 抛 出 异常 。 


如 果 你 真 的 需要 使 用 null 值 ， 但 是 null 值 不 能 和 Guava 中 的 集合 实现 一 起 工作 ， 你 只 
能 选择 其 他 实现 。 比 如 ， 用 JDK 中 的 Collections.unmodifiableList 替 代 Guava 的 
ImmutableList 





Optional 


大 多 数 情 况 下 ， 开 发 人 员 使 用 null 表 明 的 是 某 种 缺失 情形 : 可 能 是 已 经 有 一 个 默认 
值 ， 或 没有 值 ， 或 找 不 到 值 。 例 如 ，Map.get 返 回 null 就 表示 找 不 到 给 定 键 对 应 的 


值 。 
Guava 用 Optional<T> 表 示 可 能 为 null 的 T 类 型 引用 。 一 个 Optional 实 例 可 能 包含 非 
null 的 引用 (我 们 称 之 为 引用 存在 ) ， 也 可 能 什么 也 不 包括 〈 称 之 为 引用 缺失 ) 。 
它 从 不 说 包含 的 是 null 值 ， 而 是 用 存在 或 缺失 来 表示 。 但 Optional 从 不 会 包含 null 值 
引用 。 

Optional<Integer> possible = Optional.of(5); 


possible.isPresent(); // returns true 


possible.get(); // returns 5 


Optional 无 意 直接 模拟 其 他 编程 环境 中 的 "可 选 "or "可 能 ”语义 ， 但 它们 的 确 有 相似 
之 处 。 

Optional 最 常用 的 一 些 操作 被 罗列 如 下 : 

创建 Optional 实 例 (以 下 都 是 静态 方法 ) 


创建 指定 引用 的 Optional 实 例 ， 若 引用 为 
null 则 快速 失败 
Optional.absent() 创建 引用 缺失 的 Optional 实 例 


创建 指定 引用 的 Optional 实 例 ， 若 引用 为 null 
则 表示 缺失 


Optional.of(T) 


Optional. fromNullable(T) 


用 Optional 实 例 查询 引用 (以 下 都 是 非 静 态 方法 ) 


如 果 Optional 包 含 非 null 的 引用 (引用 存在 ) ， 
返回 true 


返回 Optional 所 包含 的 引用 ， 若 引用 缺失 ， 则 抛 


boolean isPresent() 


T get 
dae) 出 java.lang.lllegalStateException 
T or(T) 返回 Optional 所 包含 的 引用 ， 若 引用 缺失 ， 返 回 
指定 的 值 
T orNull() s 包含 的 引用 ， 若 引用 缺失 ， 返 回 


返回 Optional 所 包含 引用 的 单 例 不 可 变 集 ， 如 果 
Set&lt;T&gt; asSet() 引用 存在 ， 返 回 一 个 只 有 单一 元 素 的 集合 ， 如 果 
引用 缺失 ， 返 回 一 个 空 集合 。 


使 用 *Optional** 的 意义 在 哪儿 ? 


使 用 Optional 除 了 赋予 null 语 义 ， 增 加 了 可 读 性 ， 最 大 的 优点 在 于 它 是 一 种 傻瓜 式 的 
防护 。Optional 人 迫使 你 积极 思考 引用 缺失 的 情况 ， 因 为 你 必须 显 式 地 从 Optional 获 
取 引 用 。 直 接 使 用 null 很 容 易 让 人 忘掉 某 些 情形 ， 尽 管 FindBugs 可 以 帮助 查找 null 相 
关 的 问题 ， 但 是 我 们 还 是 认为 它 并 不 外 准确 地 定位 问题 根源 o 


如 同 输入 参数 ， 方 法 的 返回 值 也 可 能 是 null。 和 其 他 人 一 样 ， 你 绝对 很 可 能 会 忘记 
WAS 写 的 方法 method(a,b) 会 返回 一 个 null， 就 好 像 当 你 实现 method(a,b) 时 ， 也 很 可 
能 忘记 输入 参数 a 可 以 为 null。 将 方法 的 返回 类 型 指定 为 Optional， 也 可 以 迫使 调用 
思考 返回 的 引用 缺失 的 情形 。 


其 他 处 理 null 的 便利 方法 


当 你 需要 用 一 个 默认 值 来 替换 可 能 的 null， 请 使 

用 Objects.firstNonNull(T, T) 方法 。 如 果 两 个 值 都 是 null， 该 方法 会 抛 出 
NullPointerException。Optional 也 是 一 个 比较 好 的 替代 方案 ， 例 如 : 
Optional.of(first).or(second). 


还 有 其 它 一 些 方法 专门 处 理 null 或 空 字符 

# : emptyToNull(String)， nullToEmpty(String) > isNullOrEmpty(String) 
o 我们 想 要 强调 的 是 ， 这 些 方法 主要 用 来 与 混淆 null/ 空 的 AP| 进 行 交互 。 当 每 次 你 
写 下 混淆 null/ 空 的 代码 时 ，Guava 团 队 都 泪 流 满面 。 【好 的 做 法 是 大 只 极地 把 null 和 空 


区 分 开 ， 以 表示 不 同 的 含义 ， 在 代码 中 把 null 和 空 同 等 对 待 是 一 种 令 人 不 安 的 坏 味 
道 o 


1.2- 前 置 条 件 


原文 链接 译文 链接 译 者 : 沈 义 扬 
前 置 条 件 : 让 方法 调用 的 前 置 条 件 判断 更 简单 。 


Guava 在 Preconditions 类 中 提供 了 若干 前 置 条 件 判断 的 实用 方法 ， 我 们 强烈 建议 在 
Eclipse 中 静态 导入 这 些 方法 。 每 个 方法 都 有 三 个 变种 : 


© 没有 额外 参数 : 抛 出 的 异常 中 没有 错误 消息 ; 

e 有 一 个 Object 对 象 作 为 额外 参数 : 抛 出 的 异常 使 用 Dbject.toString() 作为 错误 
消息 ; 

e 有 一 个 String 对 象 作 为 额外 参数 ， 并 且 有 一 组 任意 数量 的 附加 Object 对 象 : 这 
个 变种 处 理 异 常 消息 的 方式 有 点 类 似 printf， 但 考虑 GWT 的 兼容 性 和 效率 ， 只 
支持 %s 指 示 符 。 例 如 : 


checkArgument(i >= 0, "Argument was %s but expected nonnegative" 
, i); 
checkArgument(i < j, "Expected i < j, but %s > %s", i, j); 


方法 声明 (不 包括 额外 参数 ) 


checkArgument (boolean) 


checkNotNull(T) 


checkState(boolean) 


checkElementIndex(int index, int size) 


checkPositionIndex(int index, int size) 


checkPositionIndexes(int start, int end, int size) 


译 者 注 : 


描述 


4 & boolean 
为 true， 用 来 格 
传递 给 方法 的 站 
数 。 


42 Evalue x & 
null， 该 方法 直 
返回 value， 
VA A RM A 
checkNotNull 


FR Bt HA 


某 些 状态 。 


检查 index 作 为 
引 值 对 某 个 列 
表 、 宁 符 串 或 3 
组 是 否 有 效 。 
index>=0 && 
index<size * 


检查 index 作 为 
置 值 对 某 个 列 
表 、 字 符 串 或 
组 是 否 有 效 。 
index>=0 && 
index<=size * 


检查 [start, end 
示 的 位 置 范围 
某 个 列表 、 字 和 
串 或 数组 是 否 7 


* 索 引 值 常用 来 查找 列表 、 字 符 串 或 数组 中 的 元 素 ， 如 List.get(int), String.charAt(int) 
* 位 置 值 和 位 置 范围 常用 来 截取 列表 、 字 符 串 或 数组 ， 如 ListSUbListnt，h 四 四 


String.substring(int) 


相 比 Apache Commons 提 供 的 类 似 方 法 ， 我 们 把 Guava 中 的 Preconditions 作 为 首 


选 。Piotr Jagielski 在 他 的 博客 中 简要 地 列举 了 一 些 理由 : 


e 在 静态 导入 后 ，Guava 方 法 非常 清楚 明晰 。checkNotNull 清 楚 地 描述 做 了 什 


么 ， 会 抛 出 什么 异常 ; 


e CheckNotNull 直 接 返 回 检查 的 参数 ， 让 你 可 以 在 构造 函数 中 保持 字段 的 单行 赋 


值 风格 : this.field = checkNotNull(field) 


e。 简单 的 、 参 数 可 变 的 printf 风 格 异 常 信息 。 监 于 这 个 优点 ， 在 JDK7 已 经 引 


入 Objects.requireNonNull 的 情况 下 ， 我 们 仍然 建议 你 使 用 checkNotNull 。 
在 编码 时 ， 如 果 茶 个 值 有 多 重 的 前 置 条 件 ， 我 们 建议 你 把 它们 放 到 不 同 的 行 ， 这 样 
有 助 于 在 调试 时 定位 o 此 外 ’ 把 每 个 前 置 条 件 放 到 不 同 的 行 > 也 可 以 帮 助 你 编 写 清 
晰 和 有 用 的 错误 消息 。 


1.3- 常 见 Object 方 法 


原文 链接 译 者 : 沈 义 扬 
equals 
当 一 个 对 象 中 的 字段 可 以 为 null 时 ， 实 现 Object.edquals 方 法 会 很 痛苦 ， 因 为 不 得 不 


分 别 对 它们 进行 null 检 查 。 使 用 Objects.equal 帮助 你 执行 null 敏 感 的 equals 判 
断 ， 从 而 避免 抛 出 NullPointerException。 例 如 : 


Objects.equal("a", "a"); // returns true 

Objects.equal(null, "a"); // returns false 
Objects.equal("a", null); // returns false 
Objects.equal(null, null); // returns true 


注意 : JDK7 引 入 的 Objects 类 提供 了 一 样 的 方法 _Objects.equals_ ° 
hashCode 


用 对 象 的 所 有 字段 作 散 列 [hash] 运 算 应 当 更 简单 。Guava 

的 Objects.hashCode(Object...) 会 对 传 入 的 字段 序列 计算 出 合理 的 、 顺 序 敏 
感 的 散 列 值 。 你 可 以 使 用 Objects.hashCode(field1, field2, ..., fieldn) 来 代替 手动 计 
算 散 列 值 。 


注意 : JDK7 引 入 的 Objects 类 提供 了 一 样 的 方法 _Objects.hash(Object...)_ 
toString 

好 的 toString 方 法 在 调试 时 是 无 价 之 宝 ， 但 是 编写 toString 方 法 有 时 候 却 很 痛苦 。 使 
用 Objects.toStringHelper 可 以 轻松 编写 有 用 的 toString 方 法 。 例 如 : 


// Returns "ClassName{x=1}" 
Objects.toStringHelper(this).add("x", 1).toString(); 

// Returns "MyObject{x=1}" 
Objects.toStringHelper("MyObject").add("x", 1).toString(); 


compare/compareTo 


实现 一 个 比较 器 [Comparator]， 或 者 直接 实现 Comparable 接 口 有 时 也 伤 不 起 。 考 虑 
一 下 这 种 情况 : 


class Person implements Comparable<Person> { 
private String lastName; 
private String firstName; 
private int zipCode; 


public int compareTo(Person other) { 
int cmp = lastName.compareTo(other.lastName); 
if (cmp != 0) { 
return cmp; 
} 


cmp = firstName.compareTo(other.firstName) ; 
if (cmp != 0) { 

return cmp; 
} 


return Integer.compare(zipCode, other.zipCode); 


RDNA KMAT > ARREDRE > LIRE o KIN DHA fe NG EG 
更 优雅 ， 为 此 ，Guava 提 供 了 ComparisonChain ° 


ComparisonChain 执 行 一 种 懒 比 较 : 它 执 行 比较 操作 直至 发 现 非 零 的 结果 ， 在 那 之 
后 的 比较 输入 将 被 忽略 。 


public int compareTo(Foo that) { 
return ComparisonChain.start() 

.compare(this.aString, that.aString) 
.compare(this.anInt, that.anInt) 
.compare(this.anEnum, that.anEnum, Ordering.natural( 

).nullsLast()) 
.result(); 

} 


这 种 Fluent 接 口 风格 的 可 读 性 更 高 ， 发 生 错 误 编码 的 几率 更 小 ， 并 且 能 避免 做 不 必 
要 的 工作 。 更 多 Guava 排 序 器 工具 可 以 在 下 一 节 里 找到 。 


1.4- 排 序 : Guava 强 大 的 ”流畅 风格 比较 器 ” 


原文 链接 EA ALD 


排序 器 [Ordering] 是 Guava 流 畅 风 格 比 较 器 [Comparator] 的 实现 ， 它 可 以 用 来 为 构建 
复杂 的 比较 器 ， 以 完成 集合 排序 的 功能 。 


从 实现 上 说 ，Ordering 实 例 就 是 一 个 特殊 的 Comparator 实 例 。Ordering 把 很 多 基于 
Comparator 的 静态 方法 (如 Collections.max) 包装 为 自己 的 实例 方法 ( 非 静 态 方 
法 ) ， 并 且 提 供 了 链 式 调用 方法 ， 来 定制 和 增强 现 有 的 比较 器 。 


创建 排序 器 : 常见 的 排序 器 可 以 由 下 面 的 静态 方法 创建 


方法 描述 
natural() oo 自 然 排 序 9 如 数字 按 大 小 ? 日 期 按 先 
Usmar raO 按 对 象 的 字符 串 形式 做 字典 排序 [lexicographical 
ordering] 


from(Comparator ) 把 给 定 的 Comparator 转 化 为 排序 器 


实现 自 定义 的 排序 器 时 ， 除 了 用 上 面 的 from 方 法 ， 也 可 以 跳 过 实现 Comparator ;而 
直接 继承 Ordering : 


Ordering<String> byLengthordering = new Ordering<String>() { 
public int compare(String left, String right) { 
return Ints.compare(left.length(), right.length()); 
} 
}; 


链 式 调用 方法 : 通过 链 式 调 用 ， 可 以 由 给 定 的 排序 器 衍生 出 其 它 排序 器 


方法 描述 


reverse() 获取 语义 相反 的 排序 器 

nullsFirst() 使 用 当前 排序 器 ， 但 额外 把 null 值 排 到 最 前 面 。 

nullsLast() 使 用 当前 排序 器 ， 但 额外 把 null 值 排 到 最 后 面 。 
合成 另 一 个 比较 器 ， 以 处 理 当 前 排序 器 中 的 相等 


compound(Comparator) aos 
情 JL o 


基于 处 理 类 型 T 的 排序 器 ， 返 回 该 类 型 的 可 和 迭代 
对 象 lterable<T> 的 排序 器 。 


对 集合 中 元 素 调用 Function， 再 按 返回 值 用 当前 
排序 器 排序 。 


lexicographical( ) 
onResultOf (Function) 
例如 ， 你 需要 下 面 这 个 类 的 排序 器 。 


class Foo { 
@Nullable String sortedBy; 
int notSortedBy; 


考虑 到 排序 器 应 该 能 处 理 sortedBy 为 null 的 情况 ， 我 们 可 以 使 用 下 面 的 链 式 调用 来 
合成 排序 器 : 


Ordering<Foo> ordering = Ordering.natural().nullsFirst().onResul 
tof(new Function<Foo, String>() { 
public String apply(Foo foo) { 
return foo.sortedBy; 


} 
}); 


当 阅 读 链 式 调用 产生 的 排序 器 时 ， 应 该 从 后 往 前 读 。 上 面 的 例子 中 ， 排 序 器 首先 调 
用 apply 方 法 获取 sortedBy 值 ， 并 把 sortedBy 为 null 的 元 素 都 放 到 最 前 面 ， 然 后 把 剩 
下 的 元 素 按 sortedBy 进 行 自然 排序 。 之 所 以 要 从 后 往 前 读 ， 是 因为 每 次 链 式 调用 都 
是 用 后 面 的 方法 包装 了 前 面 的 排序 器 。 


注 : 用 compound 方 法 包装 排序 器 时 ， 就 不 应 遵循 从 后 往 前 读 的 原则 。 为 了 避免 理 
解 上 的 混乱 ， 请 不 要 把 compound 写 在 一 长 囊 链 式 调用 的 中 间 ， 你 可 以 另 起 一 行 ， 
在 链 中 最 先 或 最 后 调用 compound 。 


超过 一 定 长 度 的 链 式 调用 ， 也 可 能 会 带 来 阅读 和 理解 上 的 难度 。 我 们 建议 按 下 面 的 
代码 这 样 ， 在 一 个 链 中 最 多 使 用 三 个 方法 。 此 外 ， 你 也 可 以 把 Function 分 离 成 中 间 
对 象 ， 让 链 式 调用 更 简洁 紧凑 。 


Ordering<Foo> ordering = Ordering.natural().nullsFirst().onResul 
tof (sortKeyFunction) 


运用 排序 器 : Guava 的 排序 器 实现 有 若干 操纵 集合 或 元 素 值 的 方法 


方法 描述 

greatestOf(Iterable iterable, int k) aes 和 迭代 对 象 中 最 大 的 K 个 
判断 可 和 迭代 对 象 是 否 已 按 排 

isOrdered(Iterable) 序 器 排序 : 允许 有 排序 值 相 
等 的 元 素 。 
判断 可 和 迭代 对 象 是 否 已 严格 

sortedCopy(Iterable) 按 排序 器 排序 : 不 允许 排序 


值 相 等 的 元 素 。 


返回 两 个 参数 中 最 小 的 那 
min(E, E) 个 。 如 果 相 等 ， 则 返回 第 一 
个 参数 。 


返回 多 个 参数 中 最 小 的 那 
个 。 如 果 有 超过 一 个 参数 都 
最 小 ， 则 返回 第 一 个 最 小 的 
参数 。 


返回 迭代 器 中 最 小 的 元 素 。 
do RT AR RP RA A 

素 ， 则 抛 出 
NoSuchElementException ° 


min(e TEMETETT) 


min(Iterable) 


1.5-Throwables : 简化 异 第 和 错误 的 传播 与 检查 


原文 链接 译 者 : 沈 义 扬 


民利 传播 


有 时 候 ， 你 会 想 把 捕获 到 的 异常 ies 出 。 这 种 情况 通常 第 发 生 在 Error 或 
RuntimeException 被 捕获 的 时 候 ， 你 没 想 捕 获 它 们 ， 但 是 声明 捕获 Throwable 和 
Exception 的 时 候 ， 也 包括 了 了 SiRuntimeException « “ Guava 提 供 了 若干 方 
法 ， 来 判断 异常 类 型 并 且 重 新 传播 异常 。 例 如 : 


try { 
someMethodThatCouldThrowAnything(); 

} catch (IKnowwhatToDoWithThisException e) { 
handle(e); 

} catch (Throwable t) { 
Throwables.propagateIfiInstanceOf(t, IOException.class); 
Throwables.propagateIfInstanceOf(t, SQLException.class); 
throw Throwables.propagate(t); 


所 有 这 些 方法 都 会 自己 决定 是 否 要 抛 出 异常 ， 但 也 能 直接 抛 出 方法 返回 的 结果 一 一 
例如 ，throw Throwables.propagate(t); 一 一 这 样 可 以 向 编译 器 声明 这 里 一 定 会 抛 出 
异常 。 


Guava 中 的 异常 传播 方法 简要 列举 如 下 


4 & Throwable < Error2.RuntimeException > 2 
接 抛 出 ; 否则 把 Throwable 包 装 成 
RuntimeException RuntimeException 抛 出 。 返 回 类 型 是 
propagate(Throwable) RuntimeException， 所 以 你 可 以 像 上 面 说 的 那样 写 
成 throw Throwables.propagate(t) ，Java 编 译 
器 会 意识 到 这 行 代码 保证 抛 出 异常 。 


void 

propagatelflnstanceOf( 

Throwable, Class<X Throwable # #! A X7 Ji E 
extends Exception>) 

throws X 


void 

propagatelfPossible( Throwable & #! 4 Errors RuntimeException 7 J 4 
Throwable) 

void 

propagatelfPossible( FY x . , 
Throwable, Class<X ee Error 或 RuntimeException 才 抛 


extends Throwable>) 
throws X 


Throwables.propagate 49 /#] + 


模仿 Java7 的 多 重 异 常 捕获 和 再 抛 出 


通常 来 说 ， 如 果 调 用 者 想 让 异常 传播 到 栈 顶 ， 他 不 需要 写 任 何 catch 代 码 块 。 因 为 他 
不 打算 从 有 异常 中 恢复 ， 他 可 能 就 不 应 该 记录 异常 ， 或 者 有 其 他 的 动作 。 他 可 能 是 想 
做 一 些 清 理工 作 ， 但 通常 来 说 ， 无 论 操 作 是 否 成 功 ， 清 理工 作 都 要 进行 ， 所 以 清理 
工作 可 能 会 放 在 finallly 代 码 块 中 。 但 有 时 候 ， 捕 获 异 常 然 后 再 抛 出 也 是 有 用 的 : 也 
许 调 用 者 想 要 在 异常 传播 之 前 统计 失败 的 次 数 ， 或 者 有 条 件 地 传播 异常 。 


当 只 对 一 种 异常 进行 捕获 和 再 抛 出 时 ’ 代码 可 能 还 是 简单 明了 的 。 但 当 多 种 异常 需 
要 处 理 时 ， 却 可 能 变 得 一 团 糟 : 


@Override public void run() { 

try { 
delegate.run(); 

} catch (RuntimeException e) { 
failures.increment(); 
throw e; 

catch (Error e) { 
failures.increment(); 
throw e; 


Java7 用 多 重 捕 获 解决 了 这 个 问题 : 


} catch (RuntimeException | Error e) { 
failures.increment(); 
throw e; 


非 Java7 用 户 却 受 困 于 这 个 问题 。 他 们 想 要 写 如 下 代码 来 统计 所 有 弄 常 ， 但 是 编译 
器 不 允许 他 们 抛 出 Throwable ( 译 者 注 : 这 种 写法 把 原本 是 Error 或 
RuntimeException 类 型 的 异常 修改 成 了 Throwable， 因 此 调用 者 不 得 不 修改 方法 签 
Ar ys 


} catch (Throwable t) { 
failures.increment(); 
throw t; 


解决 办 法 是 用 throw Throwables.propagate(t) 替 换 throw t。 在 限定 情况 下 (捕获 
Error 和 RuntimeException ) ，Throwables.propagate 和 原始 代码 有 相同 行为 。 然 
而 ， 用 Throwables.propagate 也 很 容易 写 出 有 其 他 隐藏 行为 的 代码 。 尤 其 要 注意 的 
是 ， 这 个 方案 只 适用 于 处 理 RuntimeException 或 Error。 如 果 catch 块 捕获 了 受 检 异 
常 ， 你 需要 调用 propagatelflnstanceOf 来 保留 原始 代码 的 行为 ， 因 为 
Throwables.propagate 不 能 直接 传播 受 检 蜡 常 。 


总 之 ，Throwables.propagate 的 这 种 用 法 也 就 马马虎虎 ， 在 Java7 中 就 没 必要 这 样 
做 了 。 在 其 他 Java 版 本 中 ， 它 可 以 减少 少量 的 代码 重复 ， 但 简单 地 提取 方法 进行 重 
构 也 能 做 到 这 一 点 。 此 外 ， 使 用 propagate 会 意外 地 包装 受 检 模 常 。 


非 必要 用 法 : 把 抛 出 的 Throwable 转 为 Exception 


有 少数 AP|， 尤 其 是 Java 反 射 APIl 和 (以 此 为 基础 的 ) Junit， 把 方法 声明 成 抛 出 
Throwable。 和 这 样 的 API 交 互 太 痛苦 了 ， 因 为 即使 是 最 通用 的 API 通 常 也 只 是 声明 
抛 出 Exception。 当 确定 代码 会 抛 出 Throwable， 而 不 是 Exception 或 Error 时 ， 调 用 
者 可 能 会 用 Throwables.propagate 转 化 Throwable。 这 里 有 个 用 Callable 执 行 Junit 测 
试 的 范例 : 


public Void call() throws Exception { 
try { 
FooTest.super.runTest(); 

} catch (Throwable t) { 
Throwables.propagateIfPossible(t, Exception.class); 
Throwables.propagate(t); 

} 


return null; 


在 这 儿 没 必要 调用 propagate() 方 法 ， 因 为 propagatelfPossible 传 播 了 Throwable 之 
外 的 所 有 异常 类 型 ， 第 二 行 的 propagate 就 变 得 完全 等 价 于 throw new 
RuntimeException(t) ° (AI iE : 这 个 例子 也 提醒 我 们 ，propagatelfPossible 可 能 
也 会 引起 混乱 ， 因 为 它 不 但 会 传播 参数 中 给 定 的 异常 类 型 ， 还 抛 出 Error 和 
RuntimeException ) 


这 种 模式 (或 类 似 于 throw new RuntimeException(t) 的 模式 ) 在 Google 代 码 库 中 出 
现 了 超过 30 次 。 (搜索 'propagatelfPossible* Exception.class[)];') 绝 大 多 数 情 况 
下 都 明确 用 了 ”throw new RuntimeException(t)”。 我 们 也 曾 想 过 有 

个 "throwWrappingWeirdThrowable" 方 法 处 理 Throwable 到 Exception 的 转化 。 但 考 
虑 到 我 们 用 两 行 代码 实现 了 这 个 模式 ， 除 非 我 们 也 丢弃 propagatelfPossible 方 法 ， 
不 然 定 义 这 个 throwWrappingWeirdThrowable 方 法 也 并 没有 太 大 必要 。 


Throwables.propagate 的 有 争议 用 法 


争议 一 : 把 受 检 模 常 转化 为 非 受 检 有 异常 


原则 上 ， 非 受 检 异 常 代 表 pug， 而 受 检 模 常 表示 不 可 控 的 问题 。 但 在 实际 运用 中 ， 
即使 JDK 也 有 所 误 用 4 Object.clone() ` Integer. parselnt(String)、URI(String) 
或 者 至 少 对 某 些 方法 来 说 ， 没 有 让 每 个 人 都 信服 的 答案 ， 如 URI.create(String) 
的 异常 声明 。 


因此 ， 调 用 者 有 时 不 得 不 把 受 检 蜡 常 和 非 受 检 蜡 第 做 相互 转化 : 








try { 
return Integer .parseInt(userInput); 
} catch (NumberFormatException e) { 
throw new InvalidInputException(e); 
} 


try { 
return publicInterfaceMethod.invoke(); 
} catch (IllegalAccessException e) { 
throw new AssertionError(e); 
} 


有 时 候 ， 调 用 者 会 使 用 Throwables.propagate 转 化 异常 。 这 样 做 有 没有 什么 缺点 ? 
最 主要 的 恐怕 是 代码 的 含义 不 太 明 显 。throw Throwables.propagate(ioException) 
做 了 什么 ?throw new RuntimeException(ioException) 做 了 什么 ?了 这 两 者 做 了 同样 
的 事情 ， 但 后 者 的 意思 更 简单 直接 。 前 者 却 引 起 了 疑问 : " 它 做 了 什么 ? 它 并 不 只 是 
把 异常 包装 进 RuntimeException 吧 ? 如 果 它 丨 的 只 做 了 和 包装， 为 什么 还 非得 要 写 个 
方法 ?”。 应 该 承认 ， 这 些 问 题 部 分 是 因为 "propagate” 的 语义 太 模 糊 了 (用 来 抛 出 
未 声明 的 异常 吗 ?) 。 也 许 ”WraplfChecked” 更 能 清楚 地 表达 含义 。 但 即使 方法 叫 
做 "wraplfChecked”， 用 它 来 包装 一 个 已 知 类 型 的 受 检 模 常 也 没什么 优点 。 基 至 会 有 





其 他 缺点 : 也 许 比 起 RuntimeException， 还 有 更 合适 的 类 型 一 一 如 
lllegalArgumentException。 我 们 有 时 也 会 看 到 propagate 被 用 于 传播 可 能 为 受 检 的 
异常 ， 结 果 是 代码 相 比 以 前 会 稍微 简短 点 ， 但 也 稍微 有 点 不 清晰 : 


} catch (RuntimeException e) { 
throw e; 

}catch (Exception e) { 
throw new RuntimeException(e); 


} 


} catch (Exception e) { 
throw Throwables.propagate(e); 


} 


然而 ， 我 们 似乎 故意 忽略 了 把 检查 型 异常 转化 为 非 检 查 型 异常 的 合理 性 。 在 某 些 场 
景 中 ， 这 无 疑 是 正确 的 做 法 ， 但 更 多 时 候 它 被 用 于 避免 处 理 受 检 腊 常 。 这 让 我 们 的 
话题 变 成 了 争论 受 检 异常 是 不 是 坏 主意 了 ， 我 不 想 对 此 多 做 叙述 。 但 可 以 这 样 说 ， 
Throwables.propagate 不 是 为 了 鼓励 开发 者 忽略 IOException 这 样 的 异常 。 


争议 二 : 弄 常 穿 隧 


但 是 ， 如 果 你 要 实现 不 允许 抛 出 异常 的 方法 呢 ? 了 有 时 候 你 需要 把 异常 包装 在 非 受 检 
异常 内 。 这 种 做 法 插 好 ， 但 我 们 再 次 强调 ， 没 必要 用 propagate 方 法 做 这 种 简单 的 
包装 。 实 际 上 ， 手 动 包装 可 能 更 好 : 如 果 你 手动 包装 了 所 有 异常 (而 不 仅仅 是 受 检 
异常 ) ， 那 你 就 可 以 在 另 一 端 解 包 所 有 异常 ， 并 处 理 极 少 数 特 殊 场 景 。 此 外 ， 你 可 
能 还 想 把 异常 包装 成 特定 的 类 型 ， 而 不 是 像 propagate 这 样 统一 包装 成 
RuntimeException ° 


争议 三 : 重新 抛 出 其 他 线程 产生 的 异 第 


try { 
return future.get(); 
} catch (ExecutionException e) { 
throw Throwables.propagate(e.getCause()); 


} 


对 这 样 的 代码 要 考虑 很 多 方面 : 


e ExecutionException 的 cause 可 能 是 受 检 蜡 常 ， 见 上 文 "争议 一 : 把 检查 型 异常 
转化 为 非 检 查 型 异常 *。 但 如 果 我 们 确定 future 对 应 的 任务 不 会 抛 出 受 检 弄 常 
Z? (可 能 future 表 示 runnable 任 务 的 结果 一 一 译 者 注 : 如 _ ExecutorService 
中 的 submit(Runnable task, T result) 方 法 ) 如 上 所 述 ， 你 可 以 捕获 异常 并 抛 出 
AssertionError。 尤 其 对 于 Future， 请 考虑 Futures.get 方 法 。 (TODO: 对 
future.get() 抛 出 的 另 一 个 红 常 InterruptedException 作 一 些 说 明 ) 





e ExecutionException 的 cause 可 能 直接 是 Throwable 类 型 ， 而 不 是 Exception 或 
Errore 《实际 上 这 不 大 可 能 ， 但 你 想 直接 重新 抛 出 Cause 的话， 编译 器 会 强迫 
你 考虑 这 种 可 能 性 ) 见 上 文 ?用 法 二 : 把 抛 出 Throwable 改 为 抛 出 Exception”。 

e ExecutionException 的 cause 可 能 是 非 受 检 异 常 。 如 果 是 这 样 的 话 ，cause 会 直 
接 被 Throwables.propagate 抛 出 。 不 幸 的 是 ，cause 的 堆栈 信息 反映 的 是 异常 
最 初 产 生 的 线程 ， 而 不 是 传播 异常 的 线程 。 通 常 来 说 ， 最 好 在 异常 链 中 同时 包 
含 这 两 个 线程 的 堆栈 信息 ， 就 像 ExecutionException 所 做 的 那样 。 (这 个 问题 
并 不 单单 和 propagate 方 法 相关 ; 所 有 在 其 他 线程 中 重新 抛 出 异常 的 代码 都 需 
要 考虑 这 点 ) 


异 第 原因 链 


Guava 提 供 了 如 下 三 个 有 用 的 方法 ， 让 研究 异常 的 原因 链 变 得 稍微 简便 了 ， 这 三 个 
方法 的 签名 是 不 言 自明 的 : 

Throwable getRootCause(Throwable) 

List<Throwable> getCausalChain(Throwable) 


String getStackTraceAsString(Throwable) 


2- 集 


2.1- 不 可 变 集 合 


原文 链接 译 者 : 沈 义 扬 
范例 


public static final ImmutableSet<String> COLOR_NAMES = Immutable 
Set ,of( 

W red" ; 

"orange", 

"yellow", 

"green", 

"blue", 

"purple"); 


class Foo { 
Set<Bar> bars; 
Foo(Set<Bar> bars) { 
this.bars = ImmutableSet.copyOf(bars); // defensive copy 


为 什么 要 使 用 不 可 变 


不 可 变 对 象 有 很 多 优点 ， 包 括 : 


o 当 对 象 被 不 可 信 的 库 调 用 时 ， 不 可 变形 式 是 安全 的 ; 

e 不 可 变 对 象 被 多 个 线程 调用 时 ， 不 存在 竞 态 条 件 问 题 

。 不 可 变 集合 不 需要 考虑 变化 ， 因 此 可 以 节省 时 间 和 空 闻 。 所 有 不 可 变 的 集合 都 

比 它们 的 可 变形 式 有 更 好 的 内 存 利 用 兴 (分 析 和 测试 细节 ) ; 

eo 不 可 变 对 象 因为 有 固定 不 变 ， 可 以 作为 常量 来 安全 使 用 。 
创建 对 象 的 不 可 变 找 贝 是 一 项 很 好 的 防御 性 编程 技巧 。Guava 为 所 有 JDK 标 准 集合 
类 型 和 Guava 新 集合 类 型 都 提供 了 简单 多 用 的 不 可 变 版 本 。 JDK 也 提供 了 
Collections.unmodifiableXXX 方 法 把 集合 包装 为 不 可 变形 式 ， 但 我 们 认为 不 够 好 : 


o KENMERK: 不 能 舒适 地 用 在 所 有 想 做 防御 ， 性 拷贝 的 场景 ; 
e 不 安全 : | 过 原 集 合 的 引用 进行 修改 ， 返 回 的 集合 才 是 事实 上 不 可 
变 的 ; 


o 低 效 : 包装 过 的 集合 仍然 保有 可 变 集合 的 开销 ， 比 如 并 发 修改 的 检查 、 散 列表 
的 额外 空间 ， 等 等 。 


如 果 你 没有 修改 茶 个 集合 的 需求 ， 或 者 布 望 茶 个 集合 保持 不 变 时 ， 把 它 防 御 性 地 捞 
贝 到 不 可 变 集合 是 个 很 好 的 实践 。 


重要 提示 : 所 有 Guava 不 可 变 集合 的 实现 都 不 接受 nul| 值 。 我 们 对 Google 内 部 的 代 
码 库 做 过 详细 研究 ， 发 现 只 有 5% 的 情况 需要 在 集合 中 允许 null/ 元 素 ， 剩 下 的 95% 场 
景 都 是 遇 到 nul/ 值 就 快速 失败 。 如 果 你 需要 在 不 可 集合 中 使 用 null， 请 使 用 JDK 中 
的 Collections.unmodifiableXXX 方 法 。 更 多 细节 建议 请 参考 “使 用 和 避免 hull”。 


怎么 使 用 不 可 变 集合 


不 可 变 集合 可 以 用 如 下 多 种 方式 创建 


e copyOf 方 法 ， 如 ImmutableSet. S 
e of 方法 ， 如 ImmutableSet.of(“a”, “b”, “c”) X ImmutableMap.of(“a”, 1, “b”, 2); 
e Builder t$ > 30 


public static final ImmutableSet<Color> GOOGLE_COLORS = 
ImmutableSet.<Color>builder() 
.addAl1(WEBSAFE_COLORS) 
.add(new Color(0, 191, 255)) 
,build()， 


此 外 ， 对 有 序 不 可 变 集 合 来 说 ， 排 序 是 在 构造 集合 的 时 候 完成 的 ， 如 : 


ImmutableSortedSet.of("a", "b", "c", "a", "d", "b"); 


会 在 构造 时 就 把 元 素 排序 为 ab, c,d。 


想象 中 更 智能 的 copyOf 


请 注意 ，ImmutableXXX.copyOf 方 法 会 尝试 在 安全 的 时 候 避 免 做 拷贝 一 一 实际 的 实 
现 细节 不 详 ， 但 通常 来 说 是 很 智能 的 ， 比 如 : 


ImmutableSet<String> foobar = ImmutableSet.of("foo", "bar", "baz 


"); 
thingamajig(foobar); 


void thingamajig(Collection<String> collection) { 
ImmutableList<String> defensiveCopy = ImmutableList.copyOf(c 
ollection); 


} 


在 这 段 代 码 中 ，ImmutableList.copyOf(fooban) 会 智能 地 直接 返回 foobar.asList(), 它 
是 一 个 ImmutableSet 的 常量 时 间 复 杂 度 的 List 视 图 。 作为 一 种 探索 ， 
ImmutableXXX.copyOf(ImmutableCollection) 会 试图 对 如 下 情况 避免 线性 时 间 找 
贝 : 


o 在 常量 时 间 内 使 用 底层 数据 结构 是 可 能 的 一 一 例如 ， 
ImmutableSet.copyOf(ImmutableList) 就 不 能 在 常量 时 间 内 完成 。 

© 不 会 造成 内 存 泄露 一 例如， 你 有 个 很 大 的 不 可 变 集 合 ImmutableList<String> 
hugeList > ImmutableList.copyOf(hugeList.subList(0, 10)) 就 会 显 式 地 拷贝 ， 
以 免 不 必 要 地 持 有 hugeList 的 引用 。 

e 不 改变 语义 所 以 ImmutableSet.copyOf(mylImmutableSortedSet) 会 显 式 地 
拷贝 ， 因 为 和 基于 比较 器 的 ImmutableSortedSet 相 比 ，ImmutableSet 对 
hashCode() 和 equals 有 不 同 语义 。 


在 可 能 的 情况 下 避免 线性 拷贝 ， 可 以 最 大 限度 地 减少 防御 性 编程 风格 所 带 来 的 性 能 
开销 。 











asList 视 图 


所 有 不 可 变 集合 都 有 一 个 asList() 方 法 提供 ImmutableList 视 图 ， 来 帮助 你 用 列表 形 
式 方便 地 读 取 集合 元 素 。 例 如 ， 你 可 以 使 用 sortedSet.asList().get(k) 从 
ImmutableSortedSet 中 读 取 第 k 个 最 小 元 素 。 


asList() 返 回 的 ImmutableList 通 常 是 一 一 并 不 总 是 一 一 开销 稳定 的 视图 实现 ， 而 不 
是 简单 地 把 元 素 拷 贝 进 List。 也 就 是 说 ，asList 返 回 的 列表 视图 通常 比 一 般 的 列表 平 
均 性 能 更 好 ， 比 如 ， 在 底层 集合 支持 的 情况 下 ， 它 总 是 使 用 高 效 的 contains 方 法 。 





细节 : 关联 可 变 集合 和 不 可 变 集合 


可 变 集合 接口 


Collection 

List 

Set 
SortedSet/NavigableSet 
Map 

SortedMap 

Multiset 
SortedMultiset 
Multimap 
ListMultimap 
SetMultimap 

BiMap 
ClassTolnstanceMap 


Table 


属于 **JDK 


还 


是 Guava** 


JDK 
JDK 
JDK 
JDK 
JDK 
JDK 
Guava 
Guava 
Guava 
Guava 
Guava 
Guava 
Guava 


Guava 


不 可 变 版 本 


ImmutableCollection 
ImmutableList 
ImmutableSet 
ImmutableSortedSet 
ImmutableMap 
ImmutableSortedMap 


ImmutableMultiset 


ImmutableSortedMultiset 


ImmutableMultimap 
ImmutableListMultimap 
ImmutableSetMultimap 


ImmutableBiMap 


ImmutableClassToInstanceMap 


ImmutableTable 


1024 


2.2- 新 集合 类 型 


原文 链接 译文 链接 译 者 : 沈 义 扬 ， 校 对 : 丁 一 


Guava 引 入 了 很 多 JDK 没 有 的 、 但 我 们 发 现 明 显 有 用 的 新 集合 类 型 。 这 些 新 类 型 是 
为 了 和 JDK 集 合 框架 共存 ， 而 没有 往 JDK 集 合 抽 象 中 硬 塞 其 他 概念 。 作 为 一 般 规 
则 ，Guava 集 合 非 常 精准 地 遵循 了 JDK 接 口 契 约 。 


Multiset 
统计 一 个 词 在 文档 中 出 现 了 多 少 次 ， 传 统 的 做 法 是 这 样 的 : 


Map<String, Integer> counts = new HashMap<String, Integer>(); 
for (String word : words) { 
Integer count = counts.get(word); 
if (count == null) { 
counts.put(word, 1); 
} else { 
counts.put(word, count + 1); 
} 


这 种 写法 很 策 抽 ， 也 容易 出 错 ， 并 且 不 支持 同时 收集 多 种 统计 信息 ， 如 总 词 数 。 我 
们 可 以 做 的 更 好 。 


Guava 提 供 了 一 个 新 集合 类 型 Multiset， 它 可 以 多 次 添加 相等 的 元 素 。 维 基 百 科 从 
数学 角度 这 样 定义 Multiset : "集合 [se 了 ] 概 念 的 延伸 ， 它 的 元 素 可 以 重复 出 现 ... 与 集 
合 [set] 相 同 而 与 元 组 [tuple] 相 反 的 是 ，Multiset 元 素 的 顺序 是 无 关 紧 要 的 : Multiset 
{a, a, b} 和 {a, b, a} 是 相等 的 ”。 译 者 注 : 这 里 所 说 的 集合 [set] 是 数学 上 的 概 
念 ，/MMultiset 继 承 自 JDK 中 的 Collection 接 口 ， 而 不 是 Set 接 口 ， 所 以 包含 重复 元 素 并 
没有 违反 原 有 的 接口 契约 。 


可 以 用 两 种 方式 看 待 Multiset : 


@ 没有 元 素 顺 序 限制 的 ArrayList<E> 
e Map<E, Integer>， 键 为 元 素 ， 值 为 计数 


Guava 的 Multiset API 也 结合 考虑 了 这 两 种 方式 : 当 把 Multiset 看 成 普通 的 Collection 
时 ， 它 表现 得 就 像 无 序 的 ArrayList : 


e add(E) 添 加 单个 给 定 元 素 
e iterator() 返 回 一 个 迭代 器 ， 包 含 Multiset 的 所 有 元 素 (包括 重复 的 元 素 ) 
。 size() 返 回 所 有 元 素 的 总 个 数 (包括 重复 的 元 素 ) 


当 把 Multiset 看 作 Map<E, Integer> 时 ， 它 也 提供 了 符合 性 能 期 望 的 查询 操作 : 
e COUNt(Object) 返 回 给 定 元 素 的 计数 。HashMultiset.count 的 复杂 度 为 O(1)， 





TreeMultiset.count 的 复杂 度 为 O(log n) ° 
e entrySet() 返 回 Set<Multiset.Entry<E>>， 和 和 Map 的 entrySet 类 似 。 
e elementSet() 返 回 所 有 不 重复 元 素 的 Set<E>， 和 Map 的 keySet() 类 似 。 
e 所 有 Multiset 实 现 的 内 存 消耗 随 着 不 重复 元 素 的 个 数 线性 增长 。 


值得 注意 的 是 ， 除 了 极 少 数 情况 ，Multiset 和 JDK 中 原 有 的 Collection 接 口 契 约 完 全 
— & 具体 来 说 ，TreeMultiset 在 判断 元 素 是 否 相等 时 ， 与 TreeSet 一 样 用 
compare， 而 不 是 Object.equals。 另 外 特别 注意 ，Multiset.addAII(Collection) 可 以 
添加 Collection 中 的 所 有 元 素 并 进行 计数 ， 这 上 比 用 for 循 环 往 Map 添 加 元 素 和 计数 方 
便 多 了 。 





方法 描述 
count(E) 给 定 元 素 在 Multiset 中 的 计数 
elementSet() “Multiset 中 不 重复 元 素 的 集合 ， 类 型 为 Set<E> 


和 Map 的 entrySet 类 似 ， 返 回 Set<Multiset.Entry<E>>， 其 中 包 
含 的 Entry 支 持 getElement() 和 getCount() 方 法 


add(E, int) 增加 给 定 元 素 在 Multiset 中 的 计数 


entrySet() 


"Aai 减少 给 定 元 素 在 Multiset 中 的 计数 
ene 设置 给 定 元 素 在 Multiset 中 的 计数 ， 不 可 以 为 负数 
size() 返回 集合 元 素 的 总 个 数 (包括 重复 的 元 素 ) 


Multiset 7 Map 


请 注意 ，Multiset<E> 不 是 Map<E, Integer>， 虽 然 Map 可 能 是 某 些 Multiset 实 现 的 一 
半分。 准确 来 说 Multiset 是 一 种 Collection 类 型 ， 并 履行 了 Collection 接 口 相关 的 契 
约 。 关 于 Multiset 和 Map 的 显著 区 别 还 包括 : 


e Multiset 中 的 元 素 计数 只 能 是 正 数 。 任 何 元 素 的 计数 都 不 能 为 负 ， 也 不 能 是 0 © 
elementSet() 和 entrySet() 视 图 中 也 不 会 有 这 样 的 元 素 。 

e multiset.size() 返 回 集合 的 大 小 ， 等 同 于 所 有 元 素 计 数 的 总 和 。 对 于 不 重复 元 素 
的 个 数 ， 应 使 用 elementSet().size() 方 法 。 (因此 ，add(E) 把 multiset.size() 增 
加 1 ) 

。 multiset.iterator() 会 迭代 重复 元 素 ， 因 此 迭代 长 度 等 于 multiset.size()。 

e Multiset 支 持 直接 增加 、 减 少 或 设置 元 素 的 计数 。setCount(elem, 0) 等 同 于 移 除 
PRA elem 。 

e 对 multiset 中 没有 的 元 素 ，multiset.count(elem) 始 终 返 回 0。 


Multiset 的 各 种 实现 


Guava 提 供 了 多 种 Multiset 的 实现 ， 大 致 对 应 JDK 中 Map 的 各 种 实现 : 


Map 对 应 的 *Multiset** 是 否 支 持 *null** 元 素 


HashMap HashMultiset 是 
TreeMap TreeMultiset 的 如 采 comparator 支 持 
的 话 ) 
LinkedHashMap LinkedHashMultiset 是 
ConcurrentHashMap ConcurrentHashMultiset 天 
ImmutableMap ImmutableMultiset T 
SortedMultiset 


SortedMultiset 是 Multiset 接口 的 变种 ， 它 支持 高 效 地 获取 指定 范围 的 子 集 。 比 方 
说 ， 你 可 以 用 latencies.subMultiset(0,BoundType.CLOSED, 100, 
BoundType.OPEN).size() 来 统计 你 的 站 点 中 延迟 在 100 毫 秒 以 内 的 访问 ， 然 后 把 这 
个 值 和 |atencies.size() 相 比 ， 以 获取 这 个 延迟 水 平 在 总 体 访问 中 的 比例 。 


TreeMultiset 实 现 SortedMultiset 接 口 。 在 撰写 本 文档 时 ，|lmmutableSortedMultiset 
还 在 测试 和 GWT 的 兼容 性 。 


Multimap 


每 个 有 经 验 的 Java 程 序 员 都 在 某 处 实现 过 Map<K, List<V>> 或 Map<K, Set<V>>， 
并 且 要 忍受 这 个 结构 的 策 抽 。 例 如 ，Map<K, Set<V>> 通 常用 来 表示 非 标定 有 向 

图 。Guava 的 Multimap 可 以 很 容易 地 把 一 个 键 映射 到 多 个 值 。 换 和 句 话 说 ，Multimap 
是 把 键 映射 到 任意 多 个 值 的 一 般 方式 。 


可 以 用 两 种 方式 思考 Multimap 的 概念 : " 键 -单个 值 映射 "的 集合 : 


a->ta->2a->4b ->3c->5 


或 者 " 键 - 值 集合 映射 "的 映射 : 

a == (i, 2, di) i ss SE 
一 般 来 说 ，Multimap 接 口 应 该 用 第 一 种 方式 看 待 ， 但 asMap() 视 图 返回 Map<K， 
Collection<V>>， 让 你 可 以 按 另 一 种 方式 看 待 Multimap。 重 要 的 是 ， 不 会 有 任何 键 
映射 到 空 集合 : 一 个 键 要 么 至 少 到 一 个 值 ， 要 么 根本 就 不 在 Multimap 中 。 


很 少 会 直接 使 用 Multimap 接 口 ， 更 多 时 候 你 会 用 ListMultimap 或 SetMultimap 接 口 ， 
它们 分 别 把 键 映 射 到 List 或 Set 。 


修改 Multimap 


Multimap.get(key) 以 集合 形式 返回 键 所 对 应 的 值 视图 ， 即 使 没有 任何 对 应 的 值 ， 也 
会 返回 空 集合 。ListMultimap.get(key) 返 回 List，SetMultimap.get(key) 返 回 Set。 


对 值 视图 集合 进行 的 修改 最 终 都 会 反映 到 底层 的 Multimap。 例 如 : 
Set<Person> aliceChildren = childrenMultimap.get(alice); 
aliceChildren.clear(); 


aliceChildren.add(bob) ; 
aliceChildren.add(carol); 


其 他 (更 直接 地 ) 修改 Multimap 的 方法 有 : 
方法 签名 描述 FET 


添加 键 到 单个 值 的 
映射 


putAll(K, 依次 添加 键 到 多 个 lterables.addAll(multimap.get(key), 
lterable<V>) 值 的 映射 values) 


移 除 键 到 值 的 映 


射 ; 如 这 样 的 
remove(K, V) o f multimap.get(key).remove(value) 


put(K, V) multimap.get(key).add(value) 


返回 true。 


清除 键 对 应 的 所 有 
值 ， 返 回 的 集合 包 
A > 前 映 条 
removeAll(K) oe a multimap.get(key).clear() 
集合 就 不 会 影响 
Multimap f ° 


清除 键 对 应 的 所 有 
值 ， 并 重新 把 key 关 


: E multimap.get(key).clear(); 
replaceValues(K, 联 到 |terable 中 的 每 TEE th get(key) 
lterable<V>) 个 元 素 。 返 回 的 集 l 


合 包含 所 有 之 前 映 Values) 
射 到 K 的 值 。 


Multimap 的 视图 
Multimap 还 支持 若干 强大 的 视图 : 


e asMap 为 Multimap<K, V> 提 供 Map<K,Collection<V>> 形 式 的 视图 。 返 回 的 
Map 支 持 remove 操 作 ， 并 且 会 反映 到 底层 的 Multimap， 但 它 不 支持 put 或 putAll 
操作 。 更 重要 的 是 ， 如 果 你 想 为 Multimap 中 没有 的 键 返回 null， 而 不 是 一 个 新 
的 、 可 写 的 空 集合 ， 你 就 可 以 使 用 asMap().get(key)。 (你 可 以 并 且 应 当 把 
asMap.get(key) 返 回 的 结果 转化 为 适当 的 集合 类 型 一 一 如 
SetMultimap.asMap.get(key) 的 结果 转 为 Set，ListMultimap.asMap.get(key) 的 


结果 转 为 List Java 类 型 系统 不 允许 ListMultimap 直 接 为 asMap.get(key) 返 回 
List 一 一 译 者 注 : 也 可 以 用 /Multimaps 中 的 asMap 静 态 方法 帮 你 完成 类 型 转 
换 ) 

e entries 用 Collection<Map.Entry<K, V>> 返 回 Multimap 中 所 有 " 键 -单个 值 映 

射 " 一 一 包括 重复 键 。 (对 SetMultimap， 返 回 的 是 Set ) 

keySet 用 Set 表 示 Multimap 中 所 有 不 同 的 键 。 

e keys 用 Multiset 表 示 Multimap 中 的 所 有 键 ， 每 个 键 重复 出 现 的 次 数 等 于 它 映 
射 的 值 的 个 数 。 可 以 从 这 个 Multiset 中 移 除 元 素 ， 但 不 能 做 添加 操作 ; 移 除 操 
作 会 反映 到 底层 的 Multimap。 

e values() 用 一 个 ”扁平 "的 Collection<V> 包 含 Multimap 中 的 所 有 值 。 这 有 一 点 
类 似 于 lterables.concat(multimap.asMap().values())， 但 它 直 接 返 回 了 单个 
Collection， 而 不 像 multimap.asMap().values() 那 样 是 按键 区 分 开 的 
Collection ° 
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Multimap<K, V> 不 是 Map<K,Collection<V>>， 虽 然 某 些 Multimap 实 现 中 可 能 使 用 
了 map。 它 们 之 间 的 显著 区 别 包括 : 


e Multimap.get(key) 总 是 返回 非 null、 但 是 可 能 空 的 集合 。 这 并 不 意味 着 
Multimap 为 相应 的 键 花 费 内 存 创 建 了 集合 ， 而 只 是 提供 一 个 集合 视图 方便 你 为 
键 增加 映射 值 一 一 译 者 注 : 如 果 有 这 样 的 键 ， 返 回 的 集合 只 是 包装 了 
_ Multimap? CA IRS ; 如 果 没 有 这 样 的 键 ， 返 回 的 空 集合 也 只 是 持 有 
Multimap 引 用 的 栈 对 象 ， 让 你 可 以 用 来 操作 底层 的 Multimap。 因 此 ， 返 回 的 集 
合 不 会 占据 太 多 内 存 ， 数 据 实际 上 还 是 存放 在 Multimap 中 。 

e 如 果 你 更 喜欢 像 Map 那 样 ， 为 Multimap 中 没有 的 键 返回 null， 请 使 用 asMap() 视 
图 获取 一 个 Map<K, Collection<V>>。 (或 者 用 静态 方法 Multimaps.asMap() 为 
ListMultimap 返 回 一 个 Map<K, List<V>>。 对 于 SetMultimap 和 
SortedSetMultimap， 也 有 类 似 的 静态 方法 存在 ) 

e 当 且 仅 当 有 值 映射 到 键 时 ，Multimap.containsKey(key) 才 会 返回 true。 尤 其 需 

要 注意 的 是 ， 如 果 键 k 之 前 映射 过 一 个 或 多 个 值 ， 但 它们 都 被 移 除 后 ， 

Multimap.containsKey(key) 会 返回 false ° 

Multimap.entries() 返 回 Multimap 中 所 有 " 键 -单个 值 映射 "一 一 包括 重复 键 。 如 果 

你 想 要 得 到 所 有 " 键 - 值 集合 映射 "， 请 使 用 asMap().entrySet()。 

Multimap.size() 返 回 所 有 ” 键 -单个 值 映 射 "的 个 数 ， 而 非 不 同 键 的 个 数 。 要 得 到 

不 同 键 的 个 数 ， 请 改 用 Multimap.keySet().size()。 





Multimap 的 各 种 实现 


Multimap 提 供 了 多 种 形式 的 实现 。 在 大 多 数 要 使 用 Map<K, Collection<V>> 的 地 
方 ， 你 都 可 以 使 用 它们 : 


实现 BEATA RW 值 行为 类 似 


ArrayListMultimap HashMap ArrayList 
HashMultimap HashMap HashSet 
LinkedListMultimap* LinkedHashMap* LinkedList* 
LinkedHashMultimap** LinkedHashMap LinkedHashMap 
TreeMultimap TreeMap TreeSet 
ImmutableListMultimap ImmutableMap ImmutableList 
ImmutableSetMultimap ImmutableMap ImmutableSet 


除了 两 个 不 可 变形 式 的 实现 ， 其 他 所 有 实现 都 支持 null 键 和 null 值 
*LinkedListMultimap.entries() 保 留 了 所 有 键 和 值 的 迭代 顺序 。 详 情 见 doc 链 接 。 


**LinkedHashMultimap 保 留 了 映射 项 的 插入 顺序 ， 包 括 键 插入 的 顺序 ， 以 及 键 映射 
的 所 有 值 的 插入 顺序 。 


请 注意 ， 并 非 所 有 的 Multimap 都 和 上 面 列 出 的 一 样 ， 使 用 Map<K, Collection<V>> 
来 实现 (特别 是 ， 一 些 Multimap 实 现 用 了 自 定义 的 hashTable， 以 最 小 化 开销 ) 


如 果 你 想 要 更 大 的 定制 化 ， 请 用 Multimaps.newMultimap(Map， 
Supplier<Collection>) 或 list 和 set 版 本 ， 使 用 自 定 义 的 Collection、List 或 Set 实 现 
Multimap ° 


BiMap 


传统 上 ， 实 现 键 值 对 的 双向 映射 需要 维护 两 个 单独 的 map， 并 保持 它们 间 的 同步 。 
但 这 种 方式 很 容易 出 错 ， 而 且 对 于 值 已 经 在 map 中 的 情况 ， 会 变 得 非常 混乱 。 例 
如 : 


Map<String, Integer> nameToId 
Map<Integer, String> idToName 


Maps.newHashMap(); 
Maps.newHashMap(); 


nameToId.put("Bob", 42); 

idToName.put(42, "Bob"); 

// 如 果 "Bob" 和 42 已 经 在 map 中 了 ， 会 发 生 什 么 ? 

// 如 果 我 们 总 了 同步 两 个 nap， 会 有 话 异 的 bug 发 生 ..,. 


BiMap<K, V> 是 特殊 的 Map : 


e 可 以 用 inverse() 反 转 BiMap<K, V> 的 键 值 映射 
e 保证 值 是 唯一 的 ， 因 此 values() 返 回 Set 而 不 是 普通 的 Collection 


在 BiMap 中 ， 如 果 你 想 把 键 映 射 到 已 经 存在 的 值 ， 会 抛 出 legalArgumentException 
异常 。 如 果 对 特定 值 ， 你 想 要 强制 替换 它 的 键 ， 请 使 用 BiMap.forcePut(key, 
value) ° 


BiMap<String, Integer> userId = HashBiMap.create(); 


String userForId = userId.inverse().get(id); 


BiMap 的 各 种 实现 
键 *_** 值 实现 值 **_** 键 实现 xt fz #4) **BiMap** & BL 
HashMap HashMap HashBiMap 
ImmutableMap ImmutableMap ImmutableBiMap 
EnumMap EnumMap EnumBiMap 
EnumMap HashMap EnumHashBiMap 


注 : Maps 类 中 还 有 一 些 诸 如 synchronizedBiMap 的 BiMap 工 具 方法 . 


Table 


Table<Vertex, Vertex, Double> weightedGraph = HashBasedTable.cre 
ate(); 

weightedGraph.put(vi, v2, 4); 

weightedGraph.put(vi, v3, 20); 

weightedGraph.put(v2, v3, 5); 


weightedGraph.row(vi); // returns a Map mapping v2 to 4, v3 to 2 
0 

weightedGraph.column(v3); // returns a Map mapping vi to 20, v2 
to 5 


通常 来 说 ， 当 你 想 使 用 多 个 键 做 索引 的 时 候 ， 你 可 能 会 用 类 似 Map<FirstName， 
Map<LastName, Person>> 的 实现 ， 这 种 方式 很 天 质 ， 使 用 上 也 不 友好 。Guava 为 
此 提供 了 新 集合 类 型 Table， 它 有 两 个 支持 所 有 类 型 的 键 : " 行 "和 ” 列 ”。Table 提 供 多 
种 视图 ， 以 便 你 从 各 种 角度 使 用 它 : 


e rowMap() : 用 Map<R, Map<C, V>> 表 现 Table<R, C, V>。 同 样 的 ， 
rowKeySet() 返 回 " 行 " 的 集合 Set<R>。 

e row(r) : 用 Map<C, V> 返 回 给 定 ” 行 "的 所 有 列 ， 对 这 个 map 进 行 的 写 操作 也 将 
写 入 Table 中 。 

e 类 似 的 列 访问 方法 : columnMap()、columnKeySet()、column(c)。 (基于 列 的 
访问 会 比 基 于 的 行 访问 稍微 低 效 点 ) 


e cellSet() : 用 元 素 类 型 为 Table. Cell<R, C, V> 的 Set 表 现 Table<R, C, V> ° Cell 
类 似 于 Map.Entry， 但 它 是 用 行 和 列 两 个 键 区 分 的 。 


Table 有 如 下 几 种 实现 : 


e HashBasedTable : 本 质 上 用 HashMap<R, HashMap<C, V>> 实 现 ; 

e TreeBasedTable : 本 质 上 用 TreeMap<R, TreeMap<C,V>> 实 现 ; 

e ImmutableTable : 本 质 上 用 ImmutableMap<R, ImmutableMap<C, V>> 实 现 ; 
注 : ImmutableTable 对 稀疏 或 密集 的 数据 集 都 有 优化 。 

e ArrayTable : 要 求 在 构造 时 就 指定 行 和 列 的 大 小 ， 本 质 上 由 一 个 二 维 数组 实 
现 ， 以 提升 访问 速度 和 密集 Table 的 内 存 利用 率 。 
作 原 理 有 点 不 同 ， 请 参见 Javadoc 了 解 详情 。 


ClassTolnstanceMap 


ClassTolnstanceMap 是 一 种 特殊 的 Map : 它 的 键 是 类 型 ， 而 值 是 符合 键 所 指 类 型 的 
对 象 。 


为 了 扩展 Map 接 口 ，ClassTolnstanceMap 额 外 声明 了 两 个 方法 :下 
getlnstance(Class<T>) 和 T putlnstance(Class<T>, T)， 从 而 避免 强制 类 型 转换 ， 
同时 保证 了 类 型 安全 。 


ClassTolnstanceMap 有 唯一 的 泛 型 参数 ， 通 常 称 为 B， 代 表 Map 支 持 的 所 有 类 型 的 
上 界 。 例 如 : 


ClassToInstanceMap<Number> numberDefaults=MutableClassToInstance 
Map.create(); 
numberDefaults.putInstance(Integer.class, Integer.valueOf(0)); 


Adi KEW > ClassTolnstanceMap<B> & 2 J Map<Class<? extends B>, B> 或 
者 换 名 话说 ， 是 一 个 映射 B 的 子 类 型 到 对 应 实例 的 Map。 这 让 ClassTolnstanceMap 
包含 的 泛 型 声明 有 点 令 人 困惑 ， 但 请 记 住 B 始 终 是 Map 所 支持 类 型 的 上 界 通常 B 
Æ Object ° 








e E sl > Guava 提 供 了 两 种 有 用 的 实 
: MutableClassTolnstanceMap 和 ImmutableClassTolnstanceMap ° 


RangeSet 


RangeSet 描 述 了 一 组 不 相连 的 、 非 空 的 区 间 。 当 把 一 个 区 间 添 加 到 可 变 的 
RangeSet 时 ， 所 有 相连 的 区 间 会 被 合并 ， 空 区 间 会 被 忽略 。 例 如 : 


RangeSet<Integer> rangeSet = TreeRangeSet.create(); 
rangeSet.add(Range.closed(i, 10)); // {[1, eau 

rangeSet .add(Range.closedOpen(11, 15));//A#A7### RA: {[1,10], [11,1 
5)} 

rangeSet.add(Range.closed0Open(15，20)); // 相 连 区 间 ; {[1,10], [11, 
20)} 

rangeSet.add(Range.openClosed(0，0)); // 空 区 间 ; {[1,10], [11,20)} 
rangeSet.remove(Range.open(5, 10)); //74I[1, 10]: {[1,5], [10,10 
], [11,20)} 


请 注意 ， 要 合并 Range.closed(1， O a 15) 这 样 的 区 间 ， 你 
需要 首先 用 Range.canonical(DiscreteDomain) 对 区 间 进 行 预 处 理 ， 例 如 
DiscreteDomain.integers() ° 


iz : RangeSet 不 支持 GWT， 也 不 支持 JDK5 和 更 早 版 本 ; 因为 ，RangeSet 需 要 充 
分 利用 JDK6 中 NavigableMap 的 特性 。 


RangeSet 的 视图 
RangeSet 的 实现 支持 非常 广泛 的 视图 : 


° p 返回 RangeSet 的 补 集 视图 。complement 也 是 RangeSet 类 型 ， 
含 了 不 相连 的 、 非 空 的 区 间 。 

° oa cee : 返回 RangeSet 与 给 定 Range 的 交集 视图 。 这 扩展 
了 传统 排序 集合 中 的 headSet、subSet 和 tailSet 操 作 。 

e asRanges() : 用 Set<Range<C>> 表 现 RangeSet， 这 样 可 以 遍历 其 中 的 
Range ° 

e asSet(DiscreteDomain<C>) (4xImmutableRangeSet X44) :用 
ImmutableSortedSet<C> 表 现 RangeSet， 以 区 间 中 所 有 元 素 的 形式 而 不 是 区 
间 本 身 的 形式 查看 。 (这 个 操作 不 支持 DiscreteDomain 和 RangeSet 都 没有 上 
边界 ， 或 都 没有 下 边界 的 情况 ) 


RangeSet 的 查询 方法 


为 了 方便 操作 ，RangeSet 直 接 提 供 了 若干 查询 方法 ， 其 中 最 突出 的 有 : 
e contains(C) : RangeSet 最 基本 的 操作 ， 判 断 RangeSet 中 是 否 有 任何 区 间 包 含 


给 定 元 素 。 
e rangeContaining(C): 返回 包含 给 定 元 素 的 区 间 ; 若 没 有 这 样 的 区 间 ， 则 返回 
null ° 


e encloses(Range<C>) : 简单 明了 ， 判 断 RangeSet 中 是 否 有 任何 区 间 包 括 给 
区 间 。 
e span() : 返回 包括 RangeSet 中 所 有 区 间 的 最 小 区 间 。 


RangeMap 


RangeMap 描 述 了 ”不 相交 的 、 非 空 的 区 间 ” 到 特定 值 的 映射 。 和 RangeSet 不 同 ， 
RangeMap 不 会 合并 相 邻 的 映射 ， 即 便 相 邻 的 区 间 映 射 到 相同 的 值 。 例 如 : 


RangeMap<Integer, String> rangeMap = TreeRangeMap.create(); 
rangeMap.put(Range.closed(1, 10), "foo"); //{[1,10] => "foo"} 
rangeMap.put(Range.open(3, 6), "bar"); //{[1,3] => "foo", (3,6) 
=> "bar", [6,10] => "foo"} 

rangeMap.put(Range.open(10, 20), "foo"); //{[1,3] => "foo", (3,6 
) => "bar", [6,10] => "foo", (10,20) => "foo"} 
rangeMap.remove(Range.closed(5, 11)); //{[1,3] => "foo", (3,5) = 
> "bar", (11,20) => "foo"} 


RangeMap 的 视图 
RangeMap 提 供 两 个 视图 : 


e asMapOfRanges() : 用 Map<Range<K>, V> 表 现 RangeMap。 这 可 以 用 来 遍历 
RangeMap ° 

e subRangeMap(Range<k>) : /f] RangeMap # # & | RangeMap4 # £ Range 
的 交集 视图 。 这 扩展 了 传统 的 headMap、subMap 和 tailMap 操 作 。 


2.3- 强 大 的 集合 工具 类 : java.util.Collections 中 未 
包含 的 集合 工具 


原文 链接 译文 链接 EA : 沈 义 扬 ， 校 对 : 丁 一 
尚未 完成 : Queues, Tables 工 具 类 


任何 对 JDK 集 合 框 架 有 经 验 的 程序 员 都 熟悉 和 喜欢 java. util.Collections 包含 
的 工具 方法 。Guava 沿 着 这 些 路 线 提供 了 更 多 的 工具 方法 : 适用 于 所 有 集合 的 静态 
方法 。 这 是 Guava 最 流行 和 成 熟 的 部 分 之 一 。 


我 们 用 相对 直观 的 方式 把 工具 类 与 特定 集合 接口 的 对 应 关系 归纳 如 下 : 
集合 接口 “| 名 了 JDK 还 对 应 的 wxGuavaxx 工 具 类 
x Guava 


Collections2 : 不 要 和 


Coloclon. | JDK java.util.Collections i 


List JDK Lists 

Set JDK Sets 
SortedSet JDK Sets 

Map JDK Maps 
SortedMap JDK Maps 
Queue JDK Queues 
Multiset Guava Multisets 
Multimap Guava Multimaps 
BiMap Guava Maps 

Table Guava Tables 


在 找 类 似 转 化 、 过 滤 的 方法 ? 请 看 第 四 章 ， 函 数 式 风格 。 
静态 工厂 方法 
在 JDK 7 之 前 ， 构 造 新 的 范 型 集合 时 要 讨厌 地 重复 声明 范 型 : 


List<TypeThatsTooLongForItsOwnGood> list = new ArrayList<TypeTha 
tsTooLongForItsOwnGood>( ); 


我 想 我 们 都 认为 这 很 讨厌 。 因 此 Guava 提 供 了 能 够 推断 范 型 的 静态 工厂 方法 : 


List<TypeThatsTooLongForItsOwnGood> list = Lists.newArrayList(); 
Map<KeyType, LongishValueType> map = Maps.newLinkedHashMap(); 


可 以 肯定 的 是 ，JDK7 版 本 的 钻石 操作 符 (<>) 没 有 这 样 的 麻烦 : 


List<TypeThatsTooLongForItsOwnGood> list = new ArrayList<>(); 


但 Guava 的 静态 工厂 方法 远 不 止 这 么 简单 。 用 工厂 方法 模式 ， 我 们 可 以 方便 地 在 初 
始 化 时 就 指定 起 始 元 素 。 


Set<Type> copySet = Sets.newHashSet(elements); 
List<String> theseElements = Lists.newArrayList("alpha", "beta", 
"gamma" ) ; 


此 外 ， 通 过 为 工厂 方法 命名 (Effective Java 第 一 条 ) ， 我 们 可 以 提高 集合 初始 化 大 
小 的 可 读 性 : 


List<Type> exactly100 = Lists.newArrayListWithCapacity(100) ) 
List<Type> approx100 = Lists.newArrayListWithExpectedSize(100) ; 
Set<Type> approxi100Set = Sets.newHashSetWithExpectedSize(100) ; 


确切 的 静态 工厂 方法 和 相应 的 工具 类 一 起 罗列 在 下 面 的 章节 。 


注意 : Guava 引 入 的 新 集合 类 型 没有 暴露 原始 构造 器 ， 也 没有 在 工具 类 中 提供 初始 
化 方法 。 而 是 直接 在 集合 类 中 提供 了 静态 工厂 方法 ， 例 如 : 


Multiset<String> multiset = HashMultiset.create(); 


Iterables 


在 可 能 的 情况 下 ，Guava 提 供 的 工具 方法 更 偏向 于 接受 lterable 而 不 是 Collection 类 
型 。 在 Google， 对 于 不 存放 在 主 存 的 集合 一 比如 从 数据 库 或 其 他 数据 中 心 收集 的 
结果 集 ， 因 为 实际 上 还 没有 提取 全 部 数据 ， 这 类 结果 集 都 不 能 支持 类 似 size() 的 操 
作 一 一 通常 都 不 会 用 Collection 类 型 来 表示 。 


因此 ， 很 多 你 期 望 的 支持 所 有 集合 的 操作 都 在 Iterables 类 中 。 大 多 数 lterables 
方法 有 一 个 在 lterators 类 中 的 对 应 版 本 ， 用 来 处 理 lterator 。 


截至 Guava 1.2 版 本 ，lterables 使 
用 [FluentIterable](http://docs.guava-libraries.googlecode.com/git -h: 
进行 了 补充 ， 它 包装 了 一 个 lterable 实 例 ， 并 对 许多 操作 提供 了 "luent" (4A 





用 ) 语法 。 


下 面 列 出 了 一 些 最 常用 的 工具 方法 ， 但 更 多 terables 的 函数 式 方法 将 在 第 四 章 讨 


论 。 
常规 方法 
concat (Iterable&lt;Iterableé&gt; ) 


frequency(Iterable, Object) 


partition(Iterable, int) 


getFirst(Iterable, T default) 


getLast(Iterable) 


elementsEqual(Iterable, Iterable) 


unmodifiableIterable(Iterable) 


limit(Iterable, int) 


getOnlyElement(Iterable) 


* 译 者 注 : 懒 视图 意味 着 如 果 还 没 访问 到 某 个 jterable 中 的 元 素 ， 则 不 会 对 它 进 行 


联 操作 。 


串联 多 个 iterables 的 懒 视 
图 * 


返回 对 象 在 iterable 中 出 现 
的 次 数 


把 iterable 按 指定 大 小 分 
害 ， 得 到 的 子 集 都 不 能 进 
行 修改 操作 


返回 iterable 的 第 一 个 元 
素 ， 若 iterable 为 空 则 返回 
Rita 


返回 iterable 的 最 后 一 个 元 
素 ， 若 iterable 为 空 则 抛 出 
NoSuchElementException 


如 果 两 个 iterable 中 的 所 有 


元 素 相 等 且 顺 序 一 致 ， 返 
可 true 


返回 iterable 的 不 可 变 视 图 


限制 iterable 的 元 素 个 数 限 
制 给 定 值 

获取 iterable 中 唯一 的 元 
素 ， 如 果 iterable 为 空 或 有 
多 个 元 素 ， 则 快速 失败 


Iterable<Integer> concatenated = Iterables.concat( 


Ints.asList(1, 2, 3), 


con 


5 Col 


Lisi 


5 Iter 


getl 


Ints.asList(4, 5, 6)); // concatenated &ł Z% 1, 2, 3, 4 


, 9, 6 


String lastAdded = Iterables.getLast(myLinkedHashSet ) ; 
String theElement = Iterables.getOnlyElement(thisSetIsDefinitely 


ASingleton); 
// 如 果 Set 不 是 单元 素 集 ， 就 会 出 错 了 ! 


与 Collection 方 法 相似 的 工具 方法 
通常 来 说 ，Collection 的 实现 天 然 支 持 操作 其 他 Collection， 但 却 不 能 操作 lterable 。 


下 面 的 方法 中 ， 如 果 传 入 的 lterable 是 一 个 Collection 实 例 ， 则 实际 操作 将 会 委托 给 
相应 的 Collection 接 口 方 法 。 例 如 ， 往 |terables.size 方 法 传 入 是 一 个 Collection 实 
例 ， 它 不 会 丨 的 遍历 iterator 获 取 大 小 ， 而 是 直接 调用 Collection.size。 


方法 类 似 的 *Colk 
addAll(Collection addTo, Iterable toAdd) Collection.ad: 
contains(Iterable, Object) Collection.co! 
removeAll(Iterable removeFrom, Collection toRemove) Collection.rer 
retainAll(Iterable removeFrom, Collection toRetain) Collection.ret 
size(Iterable) Collection.siz 
toArray(Iterable, Class) Collection.to/ 
isEmpty(Iterable) Collection.isE 
get(Iterable, int) List.get(int) 

toString(Iterable) Collection.tos 

Fluentiterable 


除了 上 面 和 第 四 章 提 到 的 方法 ，Fluentlterable 还 有 一 些 便利 方法 用 来 把 自己 拷贝 到 
不 可 变 集合 


ImmutableList 


ImmutableSet toImmutableSet () 
ImmutableSortedSet toImmutableSortedSet (Comparator ) 
Lists 


除了 静态 工厂 方法 和 函数 式 编程 方法 ， Lists 为 List 类 型 的 对 象 提 供 了 若干 工具 方 
法 。 

方法 描述 

Partition(List, int) 把 List 按 指定 大 小 分 害 


返回 给 定 List 的 反 转 视图 。 注 : 如 果 List 是 不 可 变 


reverse(List 
( ) 的 ， 考 虑 改 用 ImmutableList.reverse() ° 


List countUp = Ints.asList(1, 2, 3, 4, 5); 
List countDown = Lists.reverse(theList); // {5, 4, 3, 2, 1} 
List<List> parts = Lists.partition(countUp, 2);//{{1,2}, {3,4}, 


{5}} 


静态 工厂 方法 
Lists 提 供 如 下 静态 工厂 方法 : 
具体 实现 = 


basic, with elements, from Iterable , with exact capacity, with 


ArrayList expected size, ffom Iterator 


LinkedList basic, from Iterable 


Sets 


Sets 工具 类 包含 了 若干 好 用 的 方法 。 


集合 理论 方法 
我 们 提供 了 很 多 标准 的 集合 运算 〈Set-Theoretic) 方法 ， 这 些 方法 接受 Set 参 数 并 
返回 SetView > THAT: 

。 直接 当 作 Set 使 用 ， 因 为 SetView 也 实现 了 Set 接 口 ; 

e 用 copyInto(Set) 拷贝 进 另 一 个 可 变 集 合 ; 

e 用 immutableCopy() 对 自己 做 不 可 变 拷贝 。 

方法 

union(Set, Set) 

intersection(Set, Set) 

difference(Set, Set) 


symmetricDifference(Set, Set) 


使 用 范例 : 


Set<String> wordswWithPrimeLength = ImmutableSet.of("one", "two", 
"three", "six", "seven", "“eight"); 

Set<String> primes = ImmutableSet.of("two", "three", "five", "se 

ven"); 

SetView<String> intersection = Sets.intersection(primes,wordswit 

hPrimeLength); 

// intersection&"two", "three", "seven" 

return intersection.immutableCopy();// 可 以 使 用 交集 ， 但 不 可 变 拷贝 的 读 

取 效 率 更 高 


其 他 Set 工 具 方法 


ay 
3 
SK 
$ 
= 


方法 


8 


cartesianProduct(List&lt;Set&gt; ) cartesianProduct(Set... 


HT Sy way FS 


$ 


powerSet(Set) 


we Ha SE op tw AE IA 


Set<String> animals = ImmutableSet.of("gerbil", "hamster"); 
Set<String> fruits = ImmutableSet.of("apple", "orange", "banana" 
); 

Set<List<String>> product = Sets.cartesianProduct(animals, fruit 
S); 

// {{"gerbil", "apple"}, {"gerbil", "orange"}, {"gerbil", "banan 
a"}, 

// {"hamster", "apple"}, {"hamster", "orange"}, {"hamster", "ba 
nana" }} 


Set<Set<String>> animalSets = Sets.powerSet(animals); 
// {{}, {"gerbil"}, {"hamster"}, {"gerbil", "hamster"}} 


静态 工厂 方法 
Sets 提 供 如 下 静态 工厂 方法 : 
具体 实现 类 型 工厂 方法 


basic, with elements, from Iterable ,with expected size, 


HashSet 
from Iterator 
LinkedHashSet basic,from Iterable ,with expected size 


TreeSet basic, with comparator ,from Iterable 


Maps 
Maps 类 有 若干 值得 单独 说 明 的 、 很 酷 的 方法 。 


uniquelndex 


Maps.uniqueIndex(Iterable, Function) 通常 针对 的 场景 是 : 有 一 组 对 象 ， 它 
们 在 某 个 属性 上 分 别 有 独 一 无 二 的 值 ， 而 我 们 希望 能 够 按照 这 个 属性 值 查找 对 象 
译 者 注 : 这 个 方法 返回 一 个 /Map， 键 为 Function 返 回 的 属性 值 ， 值 为 /terable 


中 相应 的 元 素 ， 因 此 我 们 可 以 反复 用 这 个 /Map 进行 查找 操作 。 


比方 说 ， 我 们 有 一 堆 字 符 囊 ， 这 些 字符 串 的 长 度 都 是 独一无二 的 ， 而 我 们 希望 能 够 
按照 特定 长 度 查找 字符 串 : 





ImmutableMap<Integer, String> stringsByIndex = Maps.uniqueIndex( 
strings, 
new Function<String, Integer> () { 
public Integer apply(String string) { 
return string.length(); 
} 


}); 
如 果 索 引 值 不 是 独一无二 的 ， 请 参见 下 面 的 Multimaps.index 方 法 。 


difference 


Maps.difference(Map，Map) 用 来 比较 两 个 Map 以 获取 所 有 不 同 点 。 该 方法 返回 
MapDifference 对 象 ， 把 不 同 点 的 维 恩 图 分 解 为 : 


entriesInCommon( ) 两 个 Map 中 都 有 的 映射 项 ， 包 括 匹配 的 键 与 值 
键 相 同 但 是 值 不 同 值 映射 项 。 返 回 的 Map 的 值 类 

entriesDiffering() 型 为 MapDifference.ValueDifference ， 以 表 
示 左 右 两 个 不 同 的 值 

entriesonlyonLeft() 键 只 存在 于 左边 Map 的 映射 项 


entriesOnlyOnRight ( ) 键 只 存在 于 右边 Map 的 映射 项 


Map<String, Integer> left = ImmutableMap.of("a", 1, "b", 2, "c", 
3); 

Map<String, Integer> left = ImmutableMap.of("a", 1, "b", 2, "c", 
3); 

MapDifference<String, Integer> diff = Maps.difference(left, righ 
t); 

diff.entriesInCommon(); // {"b" => 2} 

diff.entriesInCommon(); // {"b" => 2} 


diff.entriesOnlyOnLeft(); // {"a" => 1} 
diff.entriesOnlyOnRight(); // {"d" => 5} 


处 理 BiMap 的 工具 方法 


Guava 中 处 理 BiMap 的 工具 方法 在 Maps 类 中 ， 因 为 BiMap 也 是 一 种 Map 实 现 。 


BiMap** 工 具 方 法 ** 相应 的 *Map* 工 具 方 法 
synchronizedBiMap(BiMap) Collections.synchronizedMap(Map) 


unmodifiableBiMap(BiMap) Collections.unmodifiableMap(Map) 


静态 工厂 方法 

Maps 提 供 如 下 静态 工厂 方法 : 
具体 实现 类 型 
HashMap 
LinkedHashMap 


TreeMap 


EnumMap 


ConcurrentMap : 支持 所 有 操 
作 


IdentityHashMap 


Multisets 





1 + iava util Collections ¥ XK A4% ZALE 
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工厂 方法 
basic, from Map , with expected size 
basic, from Map 


basic, from Comparator , from 
SortedMap 


from Class ,from Map 
basic 


basic 


标准 的 Collection 操 作 会 忽略 Multiset 重 复元 素 的 个 数 ， 而 只 关心 元 素 是 否 存在 于 


Multiset? > 4econtainsAllZ % ° A sh > 


Multiset 元 素 的 重复 性 : 


方法 


containsOccurrences(Multiset sup, Multiset sub) 


removeOccurrences(Multiset removeFrom, Multiset toRemove) 


retainOccurrences(Multiset removeFrom, Multiset toRetain) 


intersection(Multiset, Multiset) 


Multisets 提供 了 若干 方法 ， 以 顾及 


说 明 


xH È 
sub.cc 
<=SUF 
w true 


对 toR 
ZO 
remov 
相同 个 
修改 re 
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remov 
<=toR 
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Multiset<String> multiseti = HashMultiset.create(); 
multiseti.add("a", 2); 


Multiset<String> multiset2 = HashMultiset.create(); 
multiset2.add("a", 5); 


multiseti.containsAll(multiset2); // 返 回 true ; 因为 包含 了 所 有 不 重复 元 
素 ， 

// 虽 然 mUltiseti 实 际 上 包含 2 个 "a"， 而 multiset2 包 含 5 个 "a" 
Multisets.containsOccurrences(multiset1, multiset2); // returns 
false 


multiset2.removeOccurrences(multiset1); // multiset2 现在 包含 3 个 "a 


multiset2.removeAll(multiset1);//multiset2 移 除 所 有 "a"， 虽 然 multise 
t1 只 有 2 个 "an 
multiset2.isEmpty(); // returns true 


Multisets 中 的 其 他 工具 方法 还 包括 : 


返回 Multiset 的 不 可 变 
拷贝 ， 并 将 元 素 按 重 


copyHighestCountFirst (Multiset) 复出 现 的 次 数 做 降序 
JARS ye 


排列 

i j DEER 
unmodifiableMultiset(Multiset) ee IRAR 
unmodifiableSortedMultiset(SortedMultiset) Sen ee 

INVER? 


Multiset<String> multiset = HashMultiset.create(); 
multiset.add("a", 3); 
multiset.add("b", 5); 
multiset.add("c", 1); 


ImmutableMultiset highestCountFirst = Multisets.copyHighestCount 
First(multiset); 

//highestCountFirst > &i#¢€%entrySetfeelementSet > #{"b", "a", "c" 
} 排 列 元 素 


Multimaps 


Multimaps 提供 了 若干 值得 单独 说 明 的 通用 工具 方法 


index 


作为 Maps.uniquelndex 的 兄弟 方 

法 ， Multimaps.index(Iterable, Function) 通常 针对 的 场景 是 : 有 一 组 对 
象 ， 它 们 有 共同 的 特定 属性 ， 我 们 希望 按照 这 个 属性 的 值 查询 对 象 ， 但 属性 值 不 一 
定 是 独一无二 的 。 


比方 说 ， 我 们 想 把 字符 串 按 长 度 分 组 。 


ImmutableSet digits = ImmutableSet.of("Zero", "one", "two", "thr 
ee", "four", "five", "six", "seven", "eight", "nine"); 
Function<String, Integer> lengthFunction = new Function<String, 
Integer>() { 
public Integer apply(String string) { 
return string.length(); 
} 


je 


ImmutableListMultimap<Integer, String> digitsByLength= Multimaps 
.index(digits, lengthFunction); 

is 

* digitsByLength maps: 

* 3 => {"one", "two", ESIXAN 

* 4 => {"zero", "four", "five", "nine"} 

* 5 => {"three", "seven", "eight"} 

ah 


invertFrom 


鉴于 Multimap 可 以 把 多 个 键 映射 到 同一 个 值 ( 译 者 注 : 实际 上 这 是 任何 map 都 有 
的 特性 ) ， 也 可 以 把 一 个 键 映射 到 多 个 值 ， 反 转 Multimap 也 会 很 有 用 。Guava 提供 
了 invertFrom(Multimap toInvert, Multimap dest) ) 做 这 个 操作 ， 并 且 你 可 

以 自由 选择 反 转 后 的 Multimap 实 现 。 


注 : 如 果 你 使 用 的 是 ImmutableMultimap， 考 虑 改 
用 ImmutableMultimap.inverse() 做 反 转 。 


ArrayListMultimap<String, Integer> multimap = ArrayListMultimap. 
create(); 

multimap.putAll("b", Ints.asList(2, 4, 6)); 

multimap.putAll("a", Ints.asList(4, 2, 1)); 

multimap.putAll("c", Ints.asList(2, 5, 3)); 


TreeMultimap<Integer, String> inverse = Multimaps.invertFrom(mul 
timap, TreeMultimap<String, Integer>.create()); 

// 注 意 我 们 选择 的 实现 ， 因 为 选 了 TreeMultimap， 得 到 的 反 转 结果 是 有 序 的 

Vis 

* inverse maps: 


* 1 => { 'a"} 
* 2 => {"a", DE roy. 
* 3 => fey 
* 4 => taan, py 
* 5 => 人 Co 
* 6 => {"b"} 
= 
forMap 


想 在 Map 对 象 上 使 用 Multimap 的 方法 吗 ? forMap(Map) 把 Map 包 装 成 
SetMultimap。 这 个 方法 特别 有 用 ， 例 如 ， 与 Multimaps.invertFrom 结 合 使 用 ， 可 以 
把 多 对 一 的 Map 反 转 为 一 对 多 的 Multimap。 


Map<String, Integer> map = ImmutableMap.of("a", 1, "b", 1, "c", 
2); 

SetMultimap<String, Integer> multimap = Multimaps.forMap(map) ; 
// multimap: ["a" => {1}, "b" => {1}, "c" => {2}] 
Multimap<Integer, String> inverse = Multimaps.invertFrom(multima 
p, HashMultimap<Integer, String>.create()); 

// inverse: [1 => {"a","b"}, 2 => {"c"}] 


J+ gg 


包装 器 


Multimaps 提 供 了 传统 的 包装 方法 ， 以 及 让 你 选择 Map 和 Collection 类 型 以 自 定 义 
Multimap 实 现 的 工具 方法 。 


ye GY HK Do 


Multimap ListMultimap SetMultimap SortedSetMultime 
同 
步 
A Multimap ListMultimap SetMultimap SortedSetMultime 
€L 
装 
自 
we 
义 Multimap ListMultimap SetMultimap SortedSetMult ime 
x 
现 


自 定义 Multimap 的 方法 允许 你 指定 Multimap 中 的 特定 实现 。 但 要 注意 的 是 : 


e Multimap 假 设 对 Map 和 Supplier 产 生 的 集合 对 象 有 完全 所 有 权 。 这 些 自 定义 对 
象 应 避免 手动 更 新 ， 并 且 在 提供 给 Multimap 时 应 该 是 空 的 ， 此 外 还 不 应 该 使 用 
软 引 用 、 弱 引用 或 虚 引 用 。 

© 无 法 保证 修改 了 Multimap 以 后 ， 底 层 Map 的 内 容 是 什么 样 的 。 

e 即使 Map 和 Supplier 产 生 的 集合 都 是 线程 安全 的 ， 它 们 组 成 的 Multimap 也 不 能 
保证 并 发 操作 的 线程 安全 性 。 并 发 读 操作 是 工作 正常 的 ， 但 需要 保证 并 发 读 写 
的 话 ， 请 考虑 用 同步 包装 器 解决 。 

e 只 有 当 Map、Supplier、Supplier 产 生 的 集合 对 象 、 以 及 Multimap 疮 放 的 键 值 类 
型 都 是 可 序列 化 的 ，Multimap 才 是 可 序列 化 的 。 

e Multimap.get(key) 返 回 的 集合 对 象 和 Supplier 返 回 的 集合 对 象 并 不 是 同一 类 
型 。 但 如 果 Supplier 返 回 的 是 随机 访问 集合 ， 那 么 Multimap.get(key) 返 回 的 集 
合 也 是 可 随机 访问 的 。 


请 注意 ， 用 来 自 定 义 Multimap 的 方法 需要 一 个 Supplier 参 数 ， 以 创建 畏 新 的 集合 。 
下 面 有 个 实现 ListMultimap 的 例子 一 一 用 TreeMap 做 映射 ， 而 每 个 键 对 应 的 多 个 值 
M LinkedList #4 ° 





ListMultimap<String, Integer> myMultimap = Multimaps.newListMult 
imap ( 
Maps.<String, Collection>newTreeMap(), 
new Supplier<LinkedList>() { 
public LinkedList get() { 
return Lists.newLinkedList(); 
} 


}); 


Tables 


Tables 类 提供 了 若干 称 手 的 工具 方法 。 


自 定 义 Table 


堪 比 Multimaps.newXXXMultimap(Map, Supplier) + #7 


法 ， Tables.newCustomTable(Map, Supplier&lt;Map&gt;) 允许 你 指定 Table 
用 什么 样 的 map 实 现行 和 列 。 


// 使 用 LinkedHashMaps 替 代 HashMaps 


Table<String, Character, Integer> table = Tables.newCustomTable( 
Maps.<String, Map<Character, Integer>>newLinkedHashMap(), 

new Supplier<Map<Character, Integer>> () { 

public Map<Character, Integer> get() { 

return Maps.newLinkedHashMap(); 

} 

}); 


transpose 


transpose(Table&lt;R, C, V&gt;) 方法 允许 你 把 Table<C, R, V> 转 置 成 


Table<R, C, V>。 例 如 ， 如 果 你 在 用 Table 构 建 加 权 有 向 图 ， 这 个 方法 就 可 以 把 有 向 
图 反 转 。 


还 有 很 多 你 熟悉 和 喜欢 的 Table 包 装 类 。 然 而 ， 在 大 多 数 情 况 下 还 请 使 
用 ImmutableTable 


Unmodifiable 
Table 


RowSortedTable 


2.4- 集 合 扩 展 工 具 类 
原文 链接 译文 链接 译 者 : 沈 义 扬 ， 校 对 : 丁 一 
简介 


有 时 候 你 需要 实现 自己 的 集合 扩展 。 也 许 你 想 要 在 元 素 被 添加 到 列表 时 增加 特定 的 

行为 ， 或 者 你 想 实现 一 个 lterable， 其 底层 实际 上 是 遍历 数据 库 查询 的 结果 集 。 

Guava 为 你 ， 也 为 我 们 自己 提供 了 若干 工具 方法 ， 以 便 让 类 似 的 工作 变 得 更 简单 。 
(毕竟 ， 我 们 自己 也 要 用 这 些 工具 扩展 集合 框架 。) 


Forwarding X tf & 


针对 所 有 类 型 的 集合 接口 ，Guava 都 提供 了 Forwarding 抽 象 类 以 简化 装饰 者 模式 的 
使 用 。 


Forwarding 抽 象 类 定义 了 一 个 抽象 方法 : delegate()， 你 可 以 履 盖 这 个 方法 来 返回 
被 装饰 对 象 。 所 有 其 他 方法 都 会 直接 委托 给 delegate()。 例 如 说 : 
ForwardingList.get(int) 实 际 上 执行 了 delegate().get(int)。 


通过 创建 ForwardingXXX 的 子 类 并 实现 delegate() 方 法 ， 可 以 选择 性 地 替 盖 子 类 的 
方法 来 增加 装饰 功能 ， 而 不 需要 自己 委托 每 个 方法 一 一 译 者 注 : 因为 所 有 方法 都 默 
认 委 托 给 ”delegate() 返 回 的 对 象 ， 你 可 以 只 覆盖 需要 装饰 的 方法 。 


此 外 ， 很 多 集合 方法 都 对 应 一 个 "标准 方法 [standardxxx] 了 实现， 可 以 用 来 恢复 被 装 
饰 对 象 的 默认 行为 ， 以 提供 相同 的 优点 。 比 如 在 扩展 AbstractList 或 JDK 中 的 其 他 骨 
架 类 时 ， 可 以 使 用 类 似 standardAddAll 这 样 的 方法 。 


让 我 们 看 看 这 个 例子 。 假 定 你 想 装 饰 一 个 List， 让 其 记录 所 有 添加 进来 的 元 素 。 当 
然 ， 无 论 元 素 是 用 什么 方法 add(int, E), add(E), 或 addAll(Collection) 添加 
进来 的 ， 我 们 都 希望 进行 记录 ， 因 此 我 们 需要 履 盖 所 有 这 些 方 法 。 











class AddLoggingList<E> extends ForwardingList<E> { 
final List<E> delegate; // backing list 
@Override protected List<E> delegate() { 
return delegate; 


@Override public void add(int index, E elem) { 
log(index, elem); 
super.add(index, elem); 


} 
@Override public boolean add(E elem) { 
return standardAdd(elem); // 用 add(int，E) 实 现 


@Override public boolean addAll(Collection<? extends E> c) { 
return standardAddAll(c); // 用 add 实 现 


} 


记 住 ， 默 认 情 况 下 ， 所 有 方法 都 直接 转发 到 被 代理 对 象 ， 因 此 禾 盖 
ForwardingMap.put 并 不 会 改变 ForwardingMap.putAlI 的 行为 。 小 心 履 盖 所 有 需要 改 
变 行为 的 方法 ， 并 且 确 保 装 饰 后 的 集合 满足 接口 契约 。 


通常 来 说 ， 类 似 于 AbstractList 的 抽象 集合 骨架 类 ， 其 大 多 数 方法 在 Forwarding 装 饰 
器 中 都 有 对 应 的 "标准 方法 "实现 。 

对 提供 特定 视图 的 接口 ，Forwarding 装 饰 器 也 为 这 些 视图 提供 了 相应 的 "标准 方 

法 "实现 。 例 如 ，ForwardingMap 提 供 StandardKeySet、StandardValues 和 
StandardEntrySet 类 ， 它 们 在 可 以 的 情况 下 都 会 把 自己 的 方法 委托 给 被 装饰 的 
Map， 把 不 能 委托 的 声明 为 抽象 方法 。 


Peekinglterator 


有 时 候 ， 普 通 的 lterator 接 口 还 不 够 。 


lterators 提 供 一 个 Iterators.peekingIterator(Iterator) 方法 ， 来 把 lterator 

包装 为 PeekingIterator ， 这 是 |terator 的 子 类 ， 它 能 让 你 事先 寅 视 [ peek( ) ] 到 
下 一 次 调用 next() 返 回 的 元 素 。 

注意 : lterators.peekinglterator 返 回 的 Peekinglterator 不 支持 在 peek() 操 作 之 后 调用 
remove() 方 法 。 


举 个 例子 : 复制 一 个 List， 并 去 除 连 续 的 重复 元 素 。 


List<E> result = Lists.newArrayList(); 
PeekingIterator<E> iter = Iterators.peekingIterator(source.itera 


tor()); 
while (iter.hasNext()) { 
E current = iter.next(); 
while (iter.hasNext() && iter.peek().equals(current)) { 
// 跳 过 重复 的 元 素 
iter.next(); 


result.add(current); 


传统 的 实现 方式 需要 记录 上 一 个 元 素 ， 并 在 特定 情况 下 后 退 ， 但 这 很 难处 理 且 容 多 
出 错 。 相 较 而 言 ，Peekinglterator 在 理解 和 使 用 上 就 比较 直接 了 。 


Abstractlterator 


实现 你 自己 的 lterator? AbstractIterator 让 生活 更 轻松 。 


用 一 个 例子 来 解释 Abstractlterator 最 简单 。 比 方 说 ， 我 们 要 包装 一 个 iterator 以 跳 过 


空 值 2 


public static Iterator<String> skipNulls(final Iterator<String> 
in) { 
return new AbstractIterator<String>() { 
protected String computeNext() { 
while (in.hasNext()) { 
String s = in.next(); 
if (s != null) { 
return sS; 
} 


} 
return endofData( ); 


$ 


你 实现 了 computeNext () 方法 ， 来 计算 下 一 个 值 。 。 如 果 循 环 结束 了 也 没有 找到 下 
一 个 值 ， 请 返回 endOfData() 表 明 已 经 到 达 和 迭代 的 末尾 。 


注意 : Abstractlterator 继 承 了 Unmodifiablelterator， 所 以 禁止 实现 remove() 方 法 。 
如 果 你 需要 支持 remove() 的 迭代 器 ， 就 不 应 该 继承 Abstractlterator ° 


AbstractSequentiallterator 


有 一 些 和 迭代 器 用 其 他 方式 表示 会 更 简单 。 AbstractSequentiallterator 就 提供 
下 近代 的 另 一 种 方式 。 


= 
表示 


Iterator<Integer> powersOfTwo = new AbstractSequentialIterator<I 
nteger>(1) { // 注意 初始 值 11 
protected Integer computeNext(Integer previous) { 
return (previous == 1 << 30) ? null : previous * 2; 
} 
}; 


我 们 在 这 儿 实 现 了 computeNext(T) 方法 ， 它 能 接受 前 一 个 值 作 为 参数 。 


注意 ， 你 必须 额外 传 入 一 个 初始 值 ， 或 者 传 入 null 让 迭代 立即 结束 。 因 为 
computeNext(T) 假 定 null 值 意味 着 迭代 的 末尾 一 一 AbstractSequentiallterator 不 能 
来 实现 可 能 返回 null 的 迭代 器 。 
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原文 地 址 译文 地 址 译 者 HH 校对 : 沈 义 扬 
范例 


LoadingCache<Key, Graph> graphs = CacheBuilder .newBuilder ( ) 
.maximumSize(1000 ) 
.expireAfterwrite(10, TimeUnit .MINUTES) 
.removalListener (MY_LISTENER) 
.build( 
new CacheLoader<Key, Graph>() { 
public Graph load(Key key) throws AnyException { 
return createExpensiveGraph(key); 
} 
}); 


适用 性 


缓存 在 很 多 场景 下 都 是 相当 有 用 的 。 例 如 ， 计 算 或 检索 一 个 值 的 代价 很 高 ， 并 且 对 
同样 的 输入 需要 不 止 一 次 获取 值 的 时 候 ， 就 应 当 考 虑 使 用 缓存 。 缓存 在 很 多 场景 下 
都 是 相当 有 用 的 。 例 如 ， 计 算 或 检索 一 个 值 的 代价 很 高 ， 并 且 对 同样 的 输入 需要 不 
止 一 次 获取 值 的 时 候 ， 就 应 当 考虑 使 用 缓存 。 


Guava Cache 与 ConcurrentMap 很 相似 ， 但 也 不 完全 一 样 。 最 基本 的 区 别 是 
ConcurrentMap 会 一 直 保 存 所 有 添加 的 元 素 ， 直 到 显 式 地 移 除 。 相 对 地 ，Guava 
Cache 为 了 限制 内 存 占用 ， 通 常 都 设 定 为 自动 回收 元 素 。 在 某 些 场景 下 ， 尽 管 
LoadingCache 不 回收 元 素 ， 它 也 是 很 有 用 的 ， 因 为 它 会 自动 加 载 缓存 。 


通常 来 说 ， Guava Cache 适用 于 : 


e@ 你 愿意 消耗 一 些 内 存 空 间 来 提升 速度 。 

o 你 预料 到 某 些 键 会 被 查询 一 次 以 上 。 

o 缓存 中 存放 的 数据 总 量 不 会 超出 内 存 容 量 。 (Guava Cache 是 单个 应 用 运行 时 
的 本 地 缓存 。 它 不 把 数据 存放 到 文件 或 外 部 服务 器 。 如 果 这 不 符合 你 的 需求 ， 
请 尝试 Memcached 这 类 工具 ) 


如 果 你 的 场景 符合 上 述 的 每 一 条 ，Guava Cache 就 适合 你 。 


如 同 范例 代码 展示 的 一 样 ，Cache 实 例 通过 CacheBuilder 生 成 器 模式 获取 ， 但 是 自 
定义 你 的 缓存 才 是 最 有 趣 的 部 分 。 
注 : 如 果 你 不 需要 Cache 中 的 特性 ， 使 用 ConcurrentHashMap 有 更 好 的 内 存 效率 


但 Cache 的 大 多 数 特性 都 很 难 基于 昌 有 的 ConcurrentMap 复 制 ， 其 至 根本 不 可 
能 做 到 。 





加 载 


在 使 用 缓存 前 ， 首 先 问 自己 一 个 问题 : 有 没有 合理 的 默认 方法 来 加 载 或 计算 与 键 关 
联 的 值 ? 如 果 有 的 话 ， 你 应 当 使 用 CacheLoader。 如 果 没 有 ， 或 者 你 想 要 和 履 盖 默认 
的 加 载运 算 ， 同 时 保留 "获取 缓存 -如 果 没 有 - 则 计算 "[get-if-absent-compute] 的 原子 
语义 ， 你 应 该 在 调用 get 时 传 入 一 个 Callable 实 例 。 缓 存 元 素 也 可 以 通过 Cache.put 
方法 直接 插入 ， 但 自动 加 载 是 首选 的 ， 因 为 它 可 以 更 容易 地 推断 所 有 缓存 内 容 的 一 
致 o 


CacheLoader 


LoadingCache 是 附带 CacheLoader 构 建 而 成 的 缓存 实现 。 创 建 自己 的 
CacheLoader 通 常 只 需要 简单 地 实现 V load(K key) throws Exception 方法。 例如， 
你 可 以 用 下 面 的 代码 构建 LoadingCache : 


LoadingCache<Key, Graph> graphs = CacheBuilder .newBuilder ( ) 
.maximumSize(1000 ) 
.build( 
new CacheLoader<Key, Graph>() { 
public Graph load(Key key) throws AnyException { 
return createExpensiveGraph(key); 
} 
}); 


try { 
return graphs.get(key); 
} catch (ExecutionException e) { 
throw new OtherException(e.getCause()); 


} 


从 LoadingCache 查 询 的 正规 方式 是 使 用 get(K) 方 法 。 这 个 方法 要 么 返回 已 经 缓存 的 
值 ， 要 么 使 用 CacheLoader 向 缓存 原子 地 加 载 新 值 。 由 于 CacheLoader 可 能 抛 出 措 
常 ，LoadingCache.get(K) 也 声明 为 抛 出 ExecutionException 蜡 常 。 如 果 你 定义 的 
CacheLoader 没 有 声明 任何 检查 型 异常 ， 则 可 以 通过 getUnchecked(K) 查 找 缓存 ; 
但 必须 注意 ， 一 旦 CacheLoader 声 明了 检查 型 异常 ， 就 不 可 以 调用 
getUnchecked(k) ° 


LoadingCache<Key, Graph> graphs = CacheBuilder .newBuilder ( ) 
.expireAfterAccess(10, TimeUnit.MINUTES) 
.build( 
new CacheLoader<Key, Graph>() { 
public Graph load(Key key) { // no checked excep 
tion 
return createExpensiveGraph(key); 
} 
}); 


return graphs.getUnchecked(key); 


getAll(Iterable<? extends K>) 方 法 用 来 执行 批量 查询 。 默 认 情 况 下 ， 对 每 个 不 在 组 
存 中 的 键 ，getAll 方 法 会 单独 调用 CacheLoaderload 来 加 载 缓存 项 。 如 果 批 量 的 加 
载 比 多 个 单独 加 载 更 高 效 ， 你 可 以 重 载 CacheLoader.loadAll 来 利用 这 一 点 。 
getAll(lterable) 的 性 能 也 会 相应 提升 。 


注 : CacheLoaderjoaadAljf 的 实现 可 以 为 没有 明确 请 求 的 键 加 载 缓存 值 。 例 如 ， 为 某 
组 中 的 任意 键 计算 值 时 ， 能 够 获取 该 组 中 的 所 有 键 值 ，loaqdAl/ 方 法 就 可 以 实现 为 在 
同一 时 间 获 取 该 组 的 其 他 键 值 。 校 注 : getAll(lterable<? extends K>) 方 法 会 调用 
loadAll ， 但 会 算 选 结果 ， 只 会 返回 请 求 的 键 值 对 。 


Callable 


所 有 类 型 的 Guava Cache， 不 管 有 没有 自动 加 载 功能 ， 都 支持 get(K, Callable<V>) 
方法 。 这 个 方法 返回 缓存 中 相应 的 值 ， 或 者 用 给 定 的 Callable 运 算 并 把 结果 加 入 到 
缓存 中 。 在 整个 加 载 方法 完成 前 ， 缓 存 项 相关 的 可 观察 状态 都 不 会 更 改 。 这 个 方法 
简便 地 实现 了 模式 "如 果 有 缓存 则 返回 ; 否则 运算 、 缓 存 、 然 后 返回 "。 


Cache<Key, Graph> cache = CacheBuilder .newBuilder () 
.maximumSize (1000 ) 
.build(); // look Ma, no CacheLoader 
try { 
// If the key wasn't in the "easy to compute" group, we need 
to 
// do things the hard way. 
cache.get(key, new Callable<Key, Graph>() { 
@Override 
public Value call() throws AnyException { 
return doThingsTheHardway (key); 


} 
F); 
} catch (ExecutionException e) { 
throw new OtherException(e.getCause()); 
} 


显 式 插入 


使 用 cache.put(key, value) 方 法 可 以 直接 向 缓存 中 插入 值 ， 这 会 直接 徐 盖 掉 给 定 键 
之 前 映射 的 值 。 使 用 Cache.asMap() 视 图 提供 的 任何 方法 也 能 修改 缓存 。 但 请 注 
意 ，asMap 视 图 的 任何 方法 都 不 能 保证 缓存 项 被 原子 地 加 载 到 缓存 中 。 进 一 步 说 ， 
asMap 视 图 的 原子 运算 在 Guava Cache 的 原子 加 载 范 畴 之 外 ， 所 以 相 比 于 
Cache.asMap().putlfAbsent(K, V)，Cache.get(K, Callable<V>) 应 该 总 是 优先 使 
用 。 


缓存 回收 


一 个 残酷 的 现实 是 ， 我 们 几乎 一 定 没有 足够 的 内 存 缓存 所 有 数据 。 你 你 必须 决定 : 
什么 时 候 某 个 缓存 项 就 不 值得 保留 了 ? Guava Cache 提 供 了 三 种 基本 的 缓存 回收 方 
式 : 基于 容量 回收 、 定 时 回收 和 基于 引用 回收 。 


基于 容量 的 回收 (size-based eviction ) 


如 果 要 规定 缓存 项 的 数目 不 超过 国定 值 ， 只 需 使 
用 CacheBuilder.maximumSize(long) 。 缓 存 将 尝试 回收 最 近 没 有 使 用 或 总 体 上 
很 少 使 用 的 绥 存 项 。 一 一 警告 : 在 线 存 项 的 数目 达到 限定 值 之 前 ， 缓 存 就 可 能 进行 
回收 操作 一 一 通常 来 说 ， 这 种 情况 发 生 在 绥 存 项 的 数目 允 近 限定 值 时 。 


另外 ， 不 同 的 缓存 项 有 不 同 的 “权重 ” (weights ) 例如 ， 如 果 你 的 缓存 值 ， 占 据 
完全 不 同 的 内 存 空间 ， 你 可 以 使 用 CacheBuilder.weigher(weigher) 指定 一 个 

权重 函数 ， 并 且 用 CacheBuilder .maximumWeight(long) 指定 最 大 总 重 。 在 权重 
限定 场景 中 ， 除 了 要 注意 回收 也 是 在 重量 逼近 限定 值 时 就 进行 了 ， 还 要 知道 重量 是 
在 缓存 创建 时 计算 的 ， 因 此 要 考虑 重量 计算 的 复杂 度 。 








LoadingCache<Key, Graph> graphs = CacheBuilder .newBuilder ( ) 
.maximumWeight (100000 ) 
.weigher(new Weigher<Key, Graph>() { 
public int weigh(Key k, Graph g) { 
return g.vertices().size(); 
} 
}) 


.build( 
new CacheLoader<Key, Graph>() { 
public Graph load(Key key) { // no checked excep 
tion 
return createExpensiveGraph(key); 
} 
}); 


定时 回收 (Timed Eviction) 


CacheBuilder ` ` 提 供 两 种 定时 回收 的 方法 : 


e expireAfterAccess(long, TimeUnit) : 缓存 项 在 给 定时 间 内 没有 被 读 / 写 
访问 ， 则 回收 。 请 注意 这 种 缓存 的 回收 顺序 和 基于 大 小 回收 一 样 。 
e expireAfterWrite(long, TimeUnit) :缓存 项 在 给 定时 间 内 没有 被 写 访 问 
(ERRA) ， 则 回收 。 如 果 认 为 缓存 数据 总 是 在 固定 时 候 后 变 得 陈旧 不 可 
用 ， 这 种 回收 方式 是 可 取 的 。 


如 下 文 所 讨论 ， 定 时 回收 周期 性 地 在 写 操作 中 执行 ， 偶 尔 在 读 操作 中 执行 。 


测试 定时 回收 


对 定时 回收 进行 测试 时 ， 不 一 定 非得 花费 两 秒 钟 去 测试 两 秒 的 过 期 。 你 可 以 使 
用 Ticker 接口 和 CacheBuilder.ticker(Ticker) 方法 在 缓存 中 自 定 义 一 个 时 
间 源 ， 而 不 是 非得 用 系统 时 钟 。 


基于 引用 的 回收 (Reference-based Eviction ) 


通过 使 用 弱 引 用 的 键 、 或 弱 引 用 的 值 、 或 软 引 用 的 值 ，Guava Cache 可 以 把 缓存 设 
置 为 允许 垃圾 回收 : 


e CacheBuilder.weakKeys() :使 用 弱 引 用 存储 键 。 当 键 没有 其 它 (BRK) 
引用 时 ， 缓 存 项 可 以 被 垃圾 回收 。 因 为 垃圾 回收 仅 依赖 恒等式 (==) ， 使 用 弱 
引用 键 的 缓存 用 == 而 不 是 equals 比 较 键 。 

e CacheBuilder.weakValues() : 使 用 弱 引 用 存储 值 。 当 值 没有 其 它 〈 强 或 
软 ) 引用 时 ， 缓 存 项 可 以 被 垃圾 回收 。 因 为 垃圾 回收 仅 依赖 恒等式 (==) ， 使 
用 弱 引 用 值 的 缓存 用 == 而 不 是 equals 比 较 值 。 

e CacheBuilder.softValues() : 使 用 软 引 用 存储 值 。 软 引用 只 有 在 响应 内 
存 需 要 时 ， 才 按照 全 局 最 近 最 少 使 用 的 顺序 回收 。 考 虑 到 使 用 软 引 用 的 性 能 影 
响 ， 我 们 通常 建议 使 用 更 有 性 能 预测 性 的 缓存 大 小 限定 ( 见 上 文 ， 基 于 容量 回 
We) 。 使 用 软 引 用 值 的 缓存 同样 用 == 而 不 是 equals 比 较 值 。 


显 式 清除 


任何 时 候 ， 你 都 可 以 显 式 地 清除 缓存 项 ， 而 不 是 等 到 它 被 回收 : 


e 个 别 清除 : Cache.invalidate(key) 
e 批量 清除 : Cache.invalidateAll(keys) 
@ 清除 所 有 缓存 项 : Cache.invalidateAll() 


移 除 监听 器 


通过 CacheBuilder.removalListener(RemovalListener) ， 你 可 以 声明 一 个 监 
听 器 ， 以 便 缓 存 项 被 移 除 时 做 一 些 额 外 操作 。 缓 存 项 被 移 除 

时 ， RemovalListener 会 获取 移 除 通知 RemovalNotification ， 其 中 包含 移 除 
原因 RemovalCause 、 键 和 值 。 


请 注意 ，RemovalListener 抛 出 的 任何 异常 都 会 在 记录 到 日 志 后 被 丢弃 
[swallowed] ° 


CacheLoader<Key, DatabaseConnection> loader = new CacheLoader<Ke 
y, DatabaseConnection> () { 
public DatabaseConnection load(Key key) throws Exception { 
return openConnection(key); 


} 
Po 


RemovalListener<Key, DatabaseConnection> removalListener = new R 
emovalListener<Key, DatabaseConnection>() { 
public void onRemoval(RemovalNotification<Key, DatabaseConne 
ction> removal) { 
DatabaseConnection conn = removal.getValue(); 
conn.close(); // tear down properly 


Pi 


return CacheBuilder.newBuilder() 
.expireAfterWrite(2, TimeUnit .MINUTES) 
.removalListener(removalListener ) 
.build(loader ); 


警告 : 默认 情况 下 ， 监 听 器 方法 是 在 移 除 缓存 时 同步 调用 的 。 因 为 缓存 的 维护 和 请 
求 响应 通常 是 同时 进行 的 ， 代 价 高 兄 的 监听 器 方法 在 同步 模式 下 会 拖 慢 正常 的 缓存 
请 求 。 在 这 种 情况 下 ， 你 可 以 使 

用 RemovalListeners.asynchronous(RemovalListener, Executor) 把 监听 器 


装饰 为 异步 操作 。 


清理 什么 时 候 发 生 ? 


使 用 CacheBuilder 构 建 的 缓存 不 会 "自动 "执行 清理 和 回收 工作 ， 也 不 会 在 某 个 缓存 
项 过 期 后 马上 清理 ， 也 没有 诸如 此 类 的 清理 机 制 。 相 反 ， 它 会 在 写 操作 时 顺带 做 少 
量 的 维护 工作 ， 或 者 偶尔 在 读 操 作 时 做 如 果 写 操作 实在 太 少 的 话 。 


这 样 做 的 原因 在 于 : 如 果 要 自动 地 持续 清理 缓存 ， 就 必须 有 一 个 线程 ， 这 个 线程 会 
和 用 户 操作 竞争 共享 锁 。 此 外 ， 某 些 环 境 下 线程 创建 可 能 受 限制 ， 这 样 
CacheBuilder 就 不 可 用 了 。 


相反 ， 我 们 把 选择 权 交 到 你 手 里 。 如 果 你 的 缓存 是 高 吞吐 的 ， 那 就 无 需 担 心 缓存 的 
维护 和 清理 等 工作 。 如 果 你 的 缓存 只 会 偶尔 有 写 操作 ， 而 你 又 不 想 清理 工作 阻碍 了 
读 操 作 ， 那 么 可 以 创建 自己 的 维护 线程 ， 以 固定 的 时 间 间 隔 调 

用 Cache.cleanUp() ° ScheduledExecutorService 可 以 帮助 你 很 好 地 实现 这 
样 的 定时 调度 。 





刷新 


刷新 和 回收 不 太一 样 。 正 如 LoadingCache.refresh(K) 所 声明 ， 刷 新 表示 为 键 加 载 新 
值 ， 这 个 过 程 可 以 是 异步 的 。 在 刷新 操作 进行 时 ， 绥 存 仍然 可 以 向 其 他 线程 返回 旧 
值 ， 而 不 像 回收 操作 ， 读 缓存 的 线程 必须 等 待 新 值 加 载 完 成 。 


如 果 刷 新 过 程 抛 出 异常 ， 缓 存 将 保留 旧 值 ， 而 异常 会 在 记录 到 日 志 后 被 丢弃 
[swallowed] ° 


重 载 CacheLoaderreload(K, V) 可 以 扩展 刷新 时 的 行为 ， 这 个 方法 允许 开发 者 在 计 
算 新 值 时 使 用 上 昌 的 值 。 


// 有 些 键 不 需要 刷新 ， 并 且 我 们 希望 刷新 是 异步 完成 的 
LoadingCache<Key, Graph> graphs = CacheBuilder.newBuilder() 

.maximumSize(1000 ) 

.refreshAfterwWrite(1, TimeUnit .MINUTES) 

.build( 

new CacheLoader<Key, Graph>() { 
public Graph load(Key key) { // no checked excep 
tion 
return getGraphFromDatabase(key); 


} 


public ListenableFuture<Key, Graph> reload(final 
Key key, Graph prevGraph) { 
if (neverNeedsRefresh(key)) { 
return Futures.immediateFuture(prevGraph 
); 
selse{ 
// asynchronous! 
ListenableFutureTask<Key, Graph> task=Li 
stenableFutureTask.create(new Callable<Key, Graph>() { 
public Graph call() { 
return getGraphFromDatabase(key) 


} 
}); 
executor .execute(task); 
return task; 


} 
+); 


CacheBuilder.refreshAfterWrite(long, TimeUnit) 可 以 为 缓存 增加 自动 定时 刷新 功 
能 。 和 expireAfterWrite 相 反 ，refreshAfterWrite 通 过 定时 刷新 可 以 让 缓存 项 保持 可 
用 ， 但 请 注意 : 缓存 项 只 有 在 被 检索 时 才 会 趴 正 刷 新 〈 如 果 CacheLoaderrefresh 实 
现 为 异步 ， 那 么 检索 不 会 被 刷新 拖 慢 ) 。 因 此 ， 如 果 你 在 缓存 上 同时 声明 
expireAfterWrite 和 refreshAfterWrite， 缓 存 并 不 会 因为 刷新 盲目 地 定时 ee ， 如 果 
缓存 项 没有 被 检索 ， 那 刷新 就 不 会 趴 的 发 生 ， 缓 存 项 在 过 期 时 间 后 也 变 得 可 以 回 
收 。 


其 他 特性 


统计 


CacheBuilder.recordStats() 用 来 开启 Guava Cache 的 统计 功能 。 统 计 打 开 
后 ， Cache.stats() 方法 会 返回 CacheStats 对 象 以 提供 如 下 统计 信息 : 


e hitRate() : 缓存 命中 率 ; 
e averageLoadPenalty() : 加 载 新 值 的 平均 时 间 ， 单 位 为 纳 秒 ; 
e evictionCount() : 缓存 项 被 回收 的 总 数 ， 不 包括 显 式 清除 。 


此 外 ， 还 有 其 他 很 多 统计 信息 。 这 些 统计 信息 对 于 调整 缓存 设置 是 至 关 重 要 的 ， 在 
性 能 要 求 高 的 应 用 中 我 们 建议 密切 关注 这 些 数据 。 


asMap 视 图 


asMap 视 图 提供 了 缓存 的 ConcurrentMap 形 式 ， 但 asMap 视 图 与 缓存 的 交互 需要 注 


we 


e cache.asMap() 包 含 当 前 所 有 加 载 到 缓存 的 项 。 因 此 相应 地 ， 
cache.asMap().keySet() 包 含 当 前 所 有 已 加 载 键 ; 

easMap().get(key) 实 质 上 等 同 于 cache.getlfPresent(key)， 而 且 不 会 引起 缓存 项 
的 加 载 。 这 和 Map 的 语义 约定 一 致 。 

o 所 有 读 写 操作 都 会 重 置 相关 缓存 项 的 访问 时 间 ， 包 括 
Cache.asMap().get(Object) 方 法 和 Cache.asMap().put(K, V) 方 法 ， 但 不 包括 
Cache.asMap().containsKey(Object) 方 法 ， 也 不 包括 在 Cache.asMap() 的 集合 
视图 上 的 操作 。 比 如 ， 人 遍历 Cache.asMap().entrySet() 不 会 重 置 缓存 项 的 读 取 
时 间 。 


中 断 


缓存 加 载 方法 《如 Cache.get) 不 会 抛 出 InterruptedException。 我 们 也 可 以 让 这 些 
方法 支持 InterruptedException， 但 这 种 支持 注定 是 不 完备 的 ， 并 且 会 增加 所 有 使 用 
者 的 成 本 ， 而 只 有 少数 使 用 者 实际 获 益 。 详 情 请 继续 阅读 。 


Cache.get 请 求 到 未 缓存 的 值 时 会 遇 到 两 种 情况 : 当前 线程 加 载 值 ; 或 等 待 另 一 个 
正在 加 载 值 的 线程 。 这 两 种 情况 下 的 中 断 是 不 一 样 的 。 等 待 另 一 个 正在 加 载 值 的 线 
程 属 于 较 简 单 的 情况 : 使 用 可 中 断 的 等 待 就 实现 了 中 断 支持 ; 但 当前 线程 加 载 值 的 
情况 就 比较 复杂 了 : 因为 加 载 值 的 CacheLoader 是 由 用 户 提 供 的 ， 如 果 它 是 可 中 断 
的 ， 那 我 们 也 可 以 实现 支持 中 断 ， 否 则 我 们 也 无 能 为 力 。 


如 果 用 户 提供 的 CacheLoader 是 可 中 断 的 ， 为 什么 不 让 Cache.get 也 支持 中 断 ? 从 
某 种 意义 上 说 ， 其 实 是 支持 的 : 如 果 CacheLoader 抛 出 InterruptedException > 
Cache.get 将 立刻 返回 (就 和 其 他 异常 情况 一 样 ) ; 此 外 ， 在 加 载 缓存 值 的 线程 
中 ，Cache.get 捕 捉 到 InterruptedException 后 将 恢复 中 断 ， 而 其 他 线程 中 
InterruptedException 则 被 包装 成 了 ExecutionException ° 


原则 上 ， 我 们 可 以 拆除 包装 ， 把 ExecutionException 变 为 InterruptedException， 但 
这 会 让 所 有 的 LoadingCache 使 用 者 都 要 处 理 中 断 异 常 ， 即 使 他 们 提供 的 
CacheLoader 不 是 可 中 断 的 。 如 果 你 考虑 到 所 有 非 加 载 线 程 的 等 待 仍 可 以 被 中 断 ， 


这 种 做 法 也 许 是 值得 的 。 但 许多 缓存 只 在 单线 程 中 使 用 ， 它 们 的 用 户 仍然 必须 捕捉 
不 可 能 抛 出 的 InterruptedException 异 常 。 即 使 是 那些 跨 线 程 共享 缓存 的 用 户 ， 也 只 
是 有 时 候 能 中 断 他 们 的 get 调 用 ， 取 决 于 那个 线程 先 发 出 请 求 。 


对 于 这 个 决定 ， 我 们 的 指导 原则 是 让 缓存 始终 表现 得 好 像 是 在 当前 线程 加 载 值 。 这 
个 原则 让 使 用 缕 存 或 每 次 都 计算 值 可 以 简单 地 相互 切换 。 如 果 老 代码 (加 载 值 的 代 
码 ) 是 不 可 中 断 的 ， 那 么 新 代码 (使 用 缓存 加 载 值 的 代码 ) 多 半 也 应 该 是 不 可 中 断 
的 。 


如 上 所 述 ，Guava Cache 在 某 种 意义 上 支持 中 断 。 另 一 个 意义 上 说 ，Guava Cache 
不 支持 中 断 ， 这 使 得 LoadingCache 成 了 一 个 有 漏洞 的 抽象 : 当 加 载 过 程 被 中 断 

了 ， 就 当 作 其 他 异常 一 样 处 理 ， 这 在 大 多 数 情 况 下 是 可 以 的 ; 但 如 果 多 个 线程 在 等 
待 加 载 同 一 个 缓存 项 ， 即 使 加 载 线程 被 中 断 了 ， 它 也 不 应 该 让 其 他 线程 都 失败 (48 
获 到 包装 在 ExecutionException 里 的 InterruptedException) ， 正 确 的 行为 是 让 剩余 
的 菜 个 线程 重 试 加 载 。 为 此 ， 我 们 记录 了 一 个 bug。 然 而 ， 与 其 冒 着 风险 修复 这 个 

bug， 我 们 可 能 会 花 更 多 的 精力 去 实现 另 一 个 建议 AsyncLoadingCache， 这 个 实现 

会 返回 一 个 有 正确 中 断 行 为 的 Future 对 象 。 


4- 有 函数 式 编程 


原文 链接 译文 链接 译 者 : 沈 义 扬 ， 校 对 : TO 


ee se 
注意 事项 


截至 JDK7，Java 中 也 只 能 通过 策 抽 兄长 的 匿名 类 来 达到 近似 函数 式 编程 的 效果 。 
预计 JDK8 中 会 有 所 改变 ， 但 Guava 现 在 就 想 给 JDK5 以 上 用 户 提 供 这 类 支持 。 


过 度 使 用 Guava 哆 数 式 编程 会 导致 宛 长 、 混 乱 、 可 读 性 差 而 且 低 效 的 代码 。 这 是 迁 
今 为 止 最 容易 (也 是 最 经 常 ) 被 滥用 的 部 分 ， 如 果 你 想 通过 函数 式 风格 达成 一 行 代 
码 ， 致 使 这 行 代码 长 到 芒 唐 ，Guava 团 队 会 泪 流 满面 。 


比较 如 下 代码 : 


Function<String, Integer> lengthFunction = new Function<String, 
Integer>() { 
public Integer apply(String string) { 
return string.length(); 
} 
}; 


Predicate<String> allCaps = new Predicate<String>() { 
public boolean apply(String string) { 
return CharMatcher . JAVA_UPPER_CASE.matchesAl1lOf (string); 
} 
}; 


Multiset<Integer> lengths = HashMultiset.create( 
Iterables.transform(Iterables.filter(strings, allCaps), len 
gthFunction) ); 


或 Fluentlterable 的 版 本 


Multiset<Integer> lengths = HashMultiset.create( 
FluentIterable.from(strings) 
.filter(new Predicate<String>() { 
public boolean apply(String string) { 
return CharMatcher . JAVA_UPPER_CASE.matchesALI1Of ( 
string); 
} 
}) 


.transform(new Function<String, Integer>() { 
public Integer apply(String string) { 
return string.length(); 


} 
})); 


还 有 


Multiset<Integer> lengths = HashMultiset.create(); 
for (String string = strings) { 
if (CharMatcher.JAVA_UPPER_CASE.matchesAllOf(string)) { 
lengths.add(string.length()); 
} 


即使 用 了 静态 导入 ， 甚 至 把 Function 和 Predicate 的 声明 放 到 别 的 文件 ， 第 一 种 代码 
实现 仍然 不 简洁 ， 可 读 性 差 并 且 效 率 较 低 。 


截至 JDK7， 命 令 式 代码 仍 应 是 默认 和 第 一 选择 。 不 应 该 随便 使 用 函数 式 风 格 ， 除 
非 你 绝对 确定 以 下 两 点 之 一 : 


o 使 用 部 数 式 风格 以 后 ， 整 个 工程 的 代码 行 会 净 减 少 。 在 上 面 的 例子 中 ， 遂 数 式 
版 本 用 了 11 行 ， 命 令 式 代码 用 了 6 行 ， 把 函数 的 定义 放 到 另 一 个 文件 或 常量 
中 ， 并 不 能 帮助 减少 总 代码 行 。 

e 为 了 提高 效 府 ， 转 换 集合 的 结果 需要 懒 视图 ， 而 不 是 明确 计算 过 的 集合 。 此 
外 ， 确 保 你 已 经 阅读 和 重读 了 Effective Java 的 第 55 条 ， 并 且 除 了 阅读 本 章 后 面 
的 说 明 ， 你 还 看 正 做 了 性 能 测试 并 且 有 测试 数据 来 证 明 元 数 式 版 本 更 快 。 


请 务必 确保 ， 当 使 用 Guava 亏 数 式 的 时 候 ， 用 传统 的 命令 式 做 同样 的 事情 不 会 更 具 
可 读 性 。 尝 试 把 代码 写 下 来 ， 看 看 它 是 不 是 丨 的 那么 粮 糕 ? 会 不 会 比 你 想 尝试 的 极 
其 笨拙 的 函数 式 更 具 可 读 性 。 


Functions[ 有 函数 ] 和 Predicates[ 断 言 ] 


本 节 只 讨论 直接 与 Function 和 Predicate 打 交道 的 Guava 功 能 。 一 些 其 他 工具 类 也 
和 "函数 式 风 格 " 相 关 ， 例 如 Iterables.concat(Iterable&lt;Iterable&gt;) ， 
和 其 他 用 常量 时 间 返 回 视 图 的 方法 。 党 试看 看 2.3 节 的 集合 工具 类 。 


Guava 提 供 两 个 基本 的 函数 式 接 口 : 


e Function<A, B>， 它 声明 了 单个 方法 B apply(A input)。Function 对 象 通常 被 预 
期 为 引用 透明 的 没有 副作用 并 且 引 用 透明 性 中 的 "相等 "语义 与 equals 
一 致 ， 如 a.equals(b) 意 味 着 function.apply(a).equals(function.apply(b))。 

e Predicate<T>， 它 声明 了 单个 方法 boolean apply(T input)。Predicate 对 象 通常 
也 被 预期 为 无 副作用 元 数 ， 并 且 ” 相 等 "语义 与 equals 一 致 。 








特殊 的 断言 


字符 类 型 有 自己 特定 版 本 的 Predicate CharMatcher ， 它 通常 更 高 效 ， 并 且 在 
某 些 需求 方面 更 有 用 。CharMatcher 实 现 了 Predicate<Character>， 可 以 当 作 
Predicate 一 样 使 用 ， 要 把 Predicate 转 成 CharMatcher， 可 以 使 

用 CharMatcher.forPredicate 。 更 多 细节 请 参考 第 6 章 - 字 符 串 处 理 。 





此 外 ， 对 可 比较 类 型 和 基于 比较 逻辑 的 Predicate ，Range 类 可 以 满足 大 多 数 需求 
它 表 示 一 个 不 可 变 区 间 。Range 类 实现 了 Predicate， 用 以 判断 值 是 否 在 区 间 
内 。 例 如 ，Range.atMost(2) 就 是 个 完全 合法 的 Predicate<Integer>。 更 多 使 用 
Range 的 细节 请 参照 第 8 章 。 





操作 Functions 和 Predicates 

Functions 提 供 简 便 的 Function 构 造 和 操作 方法 ， 和 包括 : 
forMap(Map&lt;A, B&gt; ) compose(Function&lt;B, C&gt;, Function 
identity() toStringFunction() 

细节 请 参考 Javadoc ° 


相应 地 ，Predicates 提 供 了 更 多 构造 和 处 理 Predicate 的 方法 ， 下 面 是 一 些 例子 : 


instanceOf (Class) assignableFrom(Class) contains(Pattern) 
in(Collection) isNull() alwaysFalse( ) 
alwaysTrue() equalTo(Object ) compose(Predicate, 
and(Predicate...) or(Predicate...) not(Predicate) 


细节 请 参考 Javadoc。 


使 用 函数 式 编程 


Guava 提 供 了 很 多 工具 方法 ， 以 便 用 Function 或 Predicate 操 作 集 合 。 这 些 方 法 通 第 
可 以 在 集合 工具 类 找到 ， 如 lterables > Lists > Sets ，Maps，Multimaps 等 。 


断言 


断言 的 最 基本 应 用 就 是 过 滤 集 合 。 所 有 Guava 过 滤 方 法 都 返回 "视图 ” 
即 并 非 用 一 个 新 的 集合 表示 过 滤 ， 而 只 是 基于 原 集 合 的 视图 。 


译 者 注 : 








集合 类 型 


lterable 


lterator 
Collection 
Set 
SortedSet 
Map 
SortedMap 
Multimap 


Iterables.filter(Iterable, Predicate) FluentIterable. 
Iterators.filter(Iterator, Predicate) 
Collections2.filter(Collection, Predicate) 
Sets.filter(Set, Predicate) 

Sets.filter(SortedSet, Predicate) 

Maps.filterKeys(Map, Predicate) Maps.filterValues(Map 
Maps.filterKeys(SortedMap, Predicate) Maps.filterValu 


Multimaps.filterKeys(Multimap, Predicate) Multimaps.f 


*List 的 过 滤 视 图 被 省 略 了 ， 因 为 不 能 有 效 地 支持 类 似 get(int) 的 操作 。 请 改 用 
Lists.newArrayList(Collections2.filter(list, predicate)) 做 拷贝 过 滤 。 





除了 简单 过 滤 ，Guava 另 外 提供 了 若干 用 Predicate 处 理 lterable 的 工具 一 一 通常 
在 Iterables 工具 类 中 ， 或 者 是 FluentIterable 的 ”fluent” (RAA) 方 
法 。 
lterables* 方 法 签名 * 说 明 
是 否 所 有 元 素 满足 
boolean all(Iterable, Predicate) 懒 实现 : te RAUL 
不 满足 ， 不 会 继续 评 
是 否 有 任意 元 素 满 
boolean any(Iterable, Predicate) 满足 断言 ?2 懒 实现 : 
迭代 到 发 现 满足 的 万 
循环 并 返回 一 个 满 大 
me RPS AUR > 
T find(Iterable, Predicate ‘ 
ane 有 则 抛 出 
NoSuchElementEx 
REY ARAKI 
Optional&lt;T&gt; tryFind(Iterable, Predicate) 言 的 元 素 ， 若 没有 中 
= 0 ptional.absen 
返回 第 一 个 满足 元 站 
indexOf(Iterable, Predicate) 断言 的 元 素 索 引 值 ， 
有 返回 -1 
BRNA ih RU 
removelf(Iterable, Predicate) 言 的 元 素 ， 实 际 调 月 
lterator.remove()7 


到 目前 为 止 ， 函 数 最 常见 的 用 途 为 转换 集合 。 同 样 ， 所 有 的 Guava 转 换 方法 也 返回 
原 集 合 的 视图 。 


集合 类 型 转换 幸 方 法 入 

lterable Iterables.transform(Iterable, Function) FluentItera 
Iterator Iterators.transform(Iterator, Function) 

Collection Collections2.transform(Collection, Function) 

List Lists  thansrTonm( List, Funct 20m) 

Map* Maps.transformValues(Map, Function) Maps.transformE 
SortedMap* Maps.transformValues(SortedMap, Function) Maps.tran 
Multimap* Multimaps.transformValues(Multimap, Function) Multi 


ListMultimap* Multimaps.transformValues(ListMultimap, Function) M 


Table 


Tables.transformValues(Table, Function) 


*Map 和 Multimap 有 特殊 的 方法 ， 其 中 有 
个 EntryTransformer&lt;K, V1, V2&gt; 参数 ， 它 可 以 使 用 昌 的 键 值 来 计算 ， 
并 且 用 计算 结果 替换 旧 值 。 


* 对 Set 的 转换 操作 被 省 略 了 ， 因 为 不 能 有 效 支持 contains(Object) 操 作 





译 者 注 : 


懒 视图 实际 上 不 会 全 部 计算 转换 后 的 Set 元 素 ， 因 此 不 能 高 效 地 支 
持 contains(Object)。 请 改 用 Sets.newHashSet(Collections2.transform(set, 
function)) 进 行 拷贝 转换 。 


List<String> names; 

Map<String, Person> personWithName; 

List<Person> people = Lists.transform(names, Functions. forMap(pe 
rsonwithName) ); 


ListMultimap<String, String> firstNameToLastNames; 
// maps first names to all last names of people with that first 


name 


List 
rmEn 


Multimap<String, String> firstNameToName = Multimaps.transfo 
tries(firstNameToLastNames, 
new EntryTransformer<String, String, String> () { 

public String transformEntry(String firstName, String la 


stName) { 


return firstName + " " + lastName; 


} 
+); 


4- 函 数 式 编程 


可 以 组 合 Function 使 用 的 类 包括 : 


Ordering Ordering.onResultof (Function) 

Predicate Predicates.compose(Predicate, Function) 
Equivalence Equivalence. onResultOf (Function) 
Supplier Suppliers.compose(Function, Supplier) 
Function Functions.compose(Function, Function) 


此 外 ，ListenableFuture API & 44 4% 4&ListenableFuture 。Futures 也 提供 了 接 
受 AsyncFunction 参数 的 方法 。AsyncFunction 是 Function 的 变种 ， 它 允许 异步 计 
算 值 。 
Futures.transform(ListenableFuture, Function) 
Futures.transform(ListenableFuture, Function, Executor) 


Futures.transform(ListenableFuture, AsyncFunction) 


Futures.transform(ListenableFuture, AsyncFunction, Executor) 
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5- 并 发 


5.1-google Guava & 4) ListenableFuture “#77 


原文 地 址 译 者 : 罗 立 树 校对 : 方 腾 飞 


并 发 编程 是 一 个 难题 ， 但 是 一 个 强大 而 简单 的 抽象 可 以 显著 的 简化 并 发 的 编写 。 出 
于 这 样 的 考虑 ，Guava 定义 了 ListenableFuture 接 口 并 继承 了 JDK concurrent 包 下 
的 Future 接口 。 


我 们 强烈 地 建议 你 在 代码 中 多 使 用 ListenableFuture 来 代替 JDK 的 Future , 
为 : 


e 大 多 数 Futures 方法 中 需要 它 。 

e 转 到 ListenableFuture 编程 比较 容易 。 

e Guava 提 供 的 通用 公共 类 封装 了 公共 的 操作 方 方 法 ， 不 需要 提供 Future 
和 ListenableFuture 的 扩展 方法 。 


接口 


传统 JDK 中 的 Future 通 过 弄 步 的 方式 计算 返回 结果 :在 多 线程 运算 中 可 能 或 者 可 能 在 
没有 结束 返回 结果 ，Future 是 运行 中 的 多 线程 的 一 个 引用 句柄 ， 确 保 在 服务 执行 运 
回 一 个 Result。 


ListenableFuture 可 以 允许 你 注册 回调 方法 (callbacks)， 在 运算 (多 线程 执行 ) 完成 
的 时 候 进 行 调用 , 或 者 在 运算 (多 线程 执行 ) 完成 后 立即 执行 。 这 样 简单 的 改进 ， 
使 得 可 以 明显 的 支持 更 多 的 操作 ， 这 样 的 功能 在 JDK concurrent 中 的 Future 是 不 支 
持 的 。 


ListenableFuture 中 的 基础 方法 是 addListener(Runnable，Executor) ,该 
方法 会 在 多 线程 运算 完 的 时 候 ， 指 定 的 Runnable 参 数 传 入 的 对 象 会 被 指定 的 
Executor 执 行 。 


添加 回调 (Callbacks) 


多 数 用 户 喜 欢 使 用 Futures.addCallback(ListenableFuture<V>， 
FutureCallback<V>, Executor) 的 方式 , 或 者 另外 一 个 版 本 version ( 译 者 

注 :addCallback(ListenableFuture<V> future,FutureCallback<? super V> 
callback)) ， 黑 认 是 采用 MoreExecutors,sameThreadExecutor() 线 程 池 ,为 了 
简化 使 用 ，Callback 采 用 轻 量 级 的 设计 FutureCcallback&lt;V&gt; 中 实现 了 两 
个 方法 : 


e onSuccess(V) ,在 Future 成 功 的 时 候 执 行 ， 根 据 Future 结 果 来 判断 。 
e onFailure(Throwable) ,在 Future 失 败 的 时 候 执 行 ， 根 据 Future 结 果 来 判 
斯 fe} 


ListenableFuture 的 创建 


对 应 JDK 中 的 ExecutorService.submit(Callable) 提交 多 线程 异步 运算 的 方 
式 ，Guava 提供 了 ListeningExecutorService 接口 , 该 接口 返回 
ListenableFuture 而 相应 的 ExecutorService 返回 普通 的 Future 。 将 
ExecutorService 转 为 ListeningExecutorService， 可 以 使 

用 MoreExecutors.listeningDecorator(ExecutorService) 进 行 装饰 。 


ListeningExecutorService service = MoreExecutors.listeningDecora 
tor (Executors.newFixedtThreadPool(10) ); 
ListenableFuture explosion = service.submit(new Callable() { 
public Explosion call() { 
return pushBigRedButton(); 


} 


}); 
Futures.addCallback(explosion, new FutureCallback() { 


// we want this handler to run immediately after we push the b 
ig red button! 
public void onSuccess(Explosion explosion) { 
walkAwayFrom(explosion); 


public void onFailure(Throwable thrown) { 
battleArchNemesis(); // escaped the explosion! 


} 
+); 


另外 , 假如 你 是 从 FutureTask 转 换 而 来 的 , Guava 提 

供 ListenableFutureTask.create(Callable&lt;V&gt; ) 

和 ListenableFuturetTask. create(Runnable, V) .和 JDK 不 同 的 是 ， 
ListenableFutureTask 不 能 随意 被 继承 〈 译 者 注 : ListenableFutureTask 中 的 

done 方 法 实现 了 调用 的 操作 ) 。 


假如 你 喜欢 抽象 的 方式 来 设置 future 的 值 ， 而 不 是 想 实现 接口 中 的 方法 ， 可 以 考虑 
继承 抽象 类 AbstractFuture&lt;Vagt; 或 者 直接 使 用 SettableFuture ° 


假如 你 必须 将 其 他 API 提 供 的 Future 转 换 成 ListenableFuture ， 你 没有 别 的 方法 
只 能 采用 硬 编码 的 方式 有 来 

将 Future 转换 成 ListenableFuture 。 尽 可 能 地 采用 修改 原生 的 代码 返回 
ListenableFuture 会 更 好 一 些 。 


Application 


使 用 ListenableFuture 最 重要 的 理由 是 它 可 以 进行 一 系列 的 复杂 链 式 的 异步 操 
作 。 


ListenableFuture rowKeyFuture = indexService.lookUp(query); 
AsyncFunction<Rowkey, QueryResult> queryFunction = 

new AsyncFunction<RowKey, QueryResult>() { 

public ListenableFuture apply(RowKey rowKey) { 

return dataService.read(rowKey); 


} 

}; 

ListenableFuture queryFuture = Futures.transform(rowKeyFuture, q 
ueryFunction, queryExecutor); 


其 他 更 多 的 操作 可 以 更 加 有 效 的 支持 而 JDK 中 的 Future 是 没 法 支持 的 . 


不 同 的 操作 可 以 在 不 同 的 Executors 中 执行 ， 单 独 的 ListenableFuture 可 以 有 多 
个 操作 等 待 。 


当 一 个 操作 开始 的 时 候 其 他 的 一 些 操作 也 会 尽快 开始 执行 “fan- 
out’— ListenableFuture 能 够 满足 这 样 的 场景 : 促 发 所 有 的 回调 (callbacks) ° 
反之 更 简单 的 工作 是 ， 同 样 可 以 满足 “fan-in" 场 景 ， 促 发 ListenableFuture 获取 
(get) 计算 结果 ， 同 时 其 它 的 Futures 也 会 尽快 执行 : 可 以 参考 the 
implementation of Futures.allAsList ° ( 译 者 注 : fan-in 和 fan-out 是 软件 设计 
的 一 个 术语 ， 可 以 参考 这 里 : http://baike.baidu.com/view/388892.htm#1 或 者 看 这 
里 的 解析 Design Principles: Fan-In vs Fan-Out ， 这 里 fan-out 的 实现 就 是 封装 的 
ListenableFuture 通 过 回调 ， 调 用 其 它 代码 片段 。fan-in 的 意义 是 可 以 调用 其 它 
Future) 


方法 


transform(ListenableFuture&lt;A&gt;, ASsyncFunction&lt;A, B&gt;, Ex 


transform(ListenableFuture&lt;A&gt;, Function&lt;A, B&gt;, Executo 


allAsList(Iterable&lt;ListenableFuture&l1t;V&gt;&gt; ) 


successfulAsList(Iterable&lt; ListenableFuture&lt;V&gt;&gt; ) 


AsyncFunction&lt;A, B&gt; 中 提供 一 个 方 
法 ListenableFuture&lt;B&gt; apply(A input)， 它 可 以 被 用 于 异步 变换 值 。 


List<ListenableFuture> queries; 
// The queries go to all different data centers, but we want to 
wait until they're all done or failed. 


ListenableFuture<List> successfulQueries = Futures.successfulAsL 
ist(queries); 


Futures.addCallback(successfulQueries, callbackOnSuccessfulQueri 
es); 


CheckedFuture 


Guava 也 提供 了 CheckedFuture&lt;V, X extends Exception&gt; 4 

口 。 CheckedFuture 是 一 个 ListenableFuture ， 其 中 包含 了 多 个 版 本 的 get 
方法 ， 方 法 声明 抛 出 检查 异常 .这 样 使 得 创建 一 个 在 执行 逻辑 中 可 以 抛 出 异常 的 
Future 更 加 容易 。 将 ListenableFuture 转换 成 CheckedFuture ， 可 以 使 用 


Function&lt;Exceptiol 


Futures.makeChecked(ListenableFuture&lt;V&gt;, 
。 Guava 也 提供 了 CheckedFuture&lt;V, X extends Exception&gt; # 
， 其 中 包含 了 多 个 版 本 的 get 


CheckedFuture 是 一 个 Pe ee 
一 个 在 执行 逻辑 中 可 以 抛 出 异常 的 
， 可 以 使 用 


Wo 
方法 ， 方法 声明 抛 出 检查 并 第 .这 样 使 得 
Future 更 加 容 匈 。 将 ee pas CheckedFuture 
Futures. Rea er ee a ate ee V&agt;, Function&lt;Exceptiol 
。 Guava 也 提供 了 CheckedFuture&lt;V, X extends Se on 接 
CheckedFuture 是 一 个 es ， 其 中 包含 了 多 个 版 本 的 get 
一 个 在 执行 逮 辑 中 可 以 抛 出 异常 的 


Wo 
方法 ， 方法 声明 抛 出 检查 并 第 .这 样 使 得 
易 。 将 E E oe CheckedFuture ， 可 以 使 用 
Function&lt;Exceptioi 
接 


Future 更 加 容 

Futures. ee V&gt;, 

。 Guava 也 提供 了 CheckedFuture&lt;V, X extends Exceptioné&gt; 
， 其 中 包含 了 多 个 版 本 的 get 


是 一 个 PEE re 
一 个 在 执行 逻辑 中 可 以 抛 出 异常 的 


口 。 CheckedFuture 
方法 ， 方法 声明 抛 出 检查 并 第 .这 样 使 得 
易 。 将 EE wa CheckedFuture ， 可 以 使 用 
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5.2-Google-Guava Concurrent 包 里 的 Service 框 
RR XAT 
原文 地 址 译文 地 址 EH : 何 一 昕 校对 : 方 腾飞 


Guava 包 里 的 Service 接 口 用 于 封装 一 个 服务 对 象 的 运行 状态 、 包括 start 和 stop 等 方 
法 。 例 如 web 服 务 器 ，RPC 服 务 器 、 计 时 器 等 可 以 实现 这 个 接口 。 对 此 类 服务 的 状 
态 管 理 并 不 轻松 、 需 要 对 服务 的 开启 /关闭 进行 妥善 管理 、 特 别 是 在 多 线程 环境 下 尤 
为 复杂 。Guava 包 提供 了 一 些 基础 类 帮助 你 管理 复杂 的 状态 转换 逻辑 和 同步 细节 。 


使 用 一 个 服务 
一 个 服务 正常 生命 周期 有 : 


Service.State. NEW 
Service.State. STARTING 
Service.State.RUNNING 
Service.State. STOPPING 
Service.State. TERMINATED 


服务 一 旦 被 停止 就 无 法 再 重新 启动 了 。 如 果 服 务 在 starting、running、stopping 状 态 
出 现 问 题 、 会 进入 Service.State.FAILED .状态 。 调 用 aoe 方法 可 
以 异步 开 居 一 个 服务 ,同时 返回 this 对 象形 成 方法 调用 链 。 注 意 : 只 有 在 当前 服务 的 
状态 是 NEW 时 才能 调用 startAsync() 方 法 ， 因此 最 好 在 应 用 中 有 一 个 统一 的 地 方 初 
始 化 相关 服务 。 停 止 一 个 服务 也 是 类 似 的 、 使 用 异步 方法 stopAsync() 。 但 是 不 
像 startAsync(), 多 次 调用 这 个 方法 是 安全 的 。 这 是 为 了 方便 处 理 关 闭 服务 时 候 的 锁 
竞争 问题 。 


Service 也 提供 了 一 些 方法 用 于 等 待 服务 状态 转换 的 完成 : 


通过 addListener() 方法 异步 添加 监听 器 。 此 方法 允许 你 添加 一 个 
Service.Listener 、 它 会 在 每 次 服务 状态 转换 的 时 候 被 调用 。 注 意 : 最 好 在 服 
务 启动 之 前 添加 Listener (这 时 的 状态 是 NEW) 、 否 则 之 前 已 发 生 的 状态 转换 事件 
是 无 法 在 新 添加 的 Listener 上 被 重新 触发 的 。 


同步 使 用 awaitRunning() 。 这 个 方法 不 能 被 打 断 、 不 强制 捕获 异常 、 一 旦 服务 
启动 就 会 返回 。 如 果 服 务 没有 成 功 启 动 ， 会 抛 出 lllegalStateException 弄 常 。 同 样 
的 ， awaitTerminated() 方法 会 等 待 服务 达到 终止 状态 ( TERMINATED 或 者 
FAILED ) 。 两 个 方法 都 有 重 载 方法 允许 传 入 超时 时 间 。 


Service 接口 本 身 实现 起 来 会 比较 复杂 、 且 容易 碰 到 一 些 捉 摸 不 透 的 问题 。 因 此 
我 们 不 推荐 直接 实现 这 个 接口 。 而 是 请 继承 Guava 包 里 已 经 封装 好 的 基础 抽象 类 。 
每 个 基础 类 支持 一 种 特定 的 线程 模型 。 


基础 实现 类 


AbstractidleService 


AbstractIdleService 类 简单 实现 了 Service 接 口 、 其 在 running 状 态 时 不 会 执行 
任何 动作 -因此 在 running 时 也 不 需要 启动 线程 -但 需要 处 理 开启 /关闭 动作 。 要 实现 
一 个 此 类 的 服务 ， 只 需 继承 AbstractldleService 类 ， 然 后 自己 实现 startup() 

和 shutDown() 方法 就 可 以 了 。 


protected void startUp() { 
servlets.add(new GcStatsServlet()); 


protected void shutDown() {} 


如 上 面 的 例子 、 由 于 任何 请 求 到 GcStatsServlet 时 已 经 会 有 现成 线程 处 理 了 ， 所 以 
在 服务 运行 时 就 不 需要 做 什么 额外 动作 了 。 


AbstractExecutionThreadService 


AbstractExecutionThreadService 通过 单线 程 处 理 启 动 、 运 行 、 和 关闭 等 操 
作 。 你 必须 重 载 run() 方 法 ， 同 时 需要 能 响应 停止 服务 的 请 求 。 具 体 的 实现 可 以 在 一 
个 循环 内 做 处 理 : 


public void run() { 
while (isRunning()) { 
// perform a unit of work 
} 


} 


另外 ， 你 还 可 以 重 载 triggerShutdown() 方法 让 run() 方 法 结束 返回 。 


重 载 startUp() 和 shutDown() 方 法 是 可 选 的 ， 不 影响 服务 本 身 状态 的 管理 


protected void startUp() { 
dispatcher.listenForConnections(port, queue); 


protected void run() { 
Connection connection; 
while ((connection = queue.take() != POISON)) { 
process(connection); 
} 


protected void triggerShutdown() { 
dispatcher .stopListeningForConnections(queue); 
queue .put(POISON); 

} 


start() 内 部 会 调用 startUp() 方 法 ， 创 建 一 个 线程 、 然 后 在 线程 内 调用 run() 方 法 。 
stop() 会 调用 triggerShutdown() 方 法 并 且 等 待 线 程 终止 。 


AbstractScheduledService 


AbstractScheduledService 类 用 于 在 运行 时 处 理 一 些 周 期 性 的 任务 。 子 类 可 以 
实现 runoneIteration() 方法 定义 一 个 周期 执行 的 任务 ， 以 及 相应 的 startUp() 和 
shutDown() 方 法 。 为 了 能 够 描述 执行 周期 ， 你 需要 实现 scheduler() 方法 。 通 常 
情况 下 ， 你 可 以 使 用 AbstractScheduledService.Scheduler 类 提供 的 两 种 调度 
器 : newFixedRateSchedule(initialDelay, delay, TimeUnit) 

和 newFixedDelaySchedule(initialDelay, delay, TimeUnit) ， 类 似 于 JDK 
并 发 包 中 ScheduledExecutorService 类 提供 的 两 种 调度 方式 。 如 要 自 定 义 
schedules 则 可 以 使 用 Customscheduler 类 来 辅助 实现 ; 具体 用 法 见 javadoc。 


AbstractService 


如 需要 自 定义 的 线程 管理 、 可 以 通过 扩展 AbstractService 类 来 实现 。 一 般 情况 
下 、 使 用 上 面 的 几 个 实现 类 就 已 经 满足 需求 了 ， 但 如 果 在 服务 执行 过 程 中 有 一 些 特 
定 的 线程 处 理 需 求 、 则 建议 继承 AbstractService 类 。 


继承 AbstractService 方 法 必须 实现 两 个 方法 . 


e doStart() : 首次 调用 startAsync() 时 会 同时 调用 doStart(),doStart() 内 部 需要 
处 理 所 有 的 初始 化 工作 、 如 果 启 动 成 功 则 调用 notifyStarted() 方法 ; BA 
失败 则 调用 notifyFailed() 

e doStop() :首次 调用 stopAsync() 会 同时 调用 doStop(),doStop() 要 做 的 事情 就 
是 停止 服务 ， 如 果 停 止 成 功 则 调用 notifyStopped() 方法 ; 停止 失败 则 调用 

notifyFailed() 方法 。 


doStart 和 doStop 方 法 的 实现 需要 考虑 下 性 能 ， 尽 可 能 的 低 延 迟 。 如 果 初 始 化 的 开销 
较 大 ， 如 读 文件 ， 打 开 网 络 连 接 ， 或 者 其 他 任何 可 能 引起 阻塞 的 操作 ， 建 议 移 到 另 
外 一 个 单独 的 线程 去 处 理 。 


使 用 ServiceManager 


除了 对 Service 接 口 提供 基础 的 实现 类 ，Guava 还 提供 了 ServiceManager 类 使 得 
涉及 到 多 个 Service 集 合 的 操作 更 加 容易。 通过 实例 化 ServiceManager 类 来 创建 一 
个 Service 集 合 ， 你 可 以 通过 以 下 方法 来 管理 它们 : 


e startAsync() : 将 启动 所 有 被 管理 的 服务 。 如 果 当 前 服务 的 状态 都 是 NEW 
的 话 、 那 么 你 只 能 调用 该 方法 一 次 、 这 跟 Service#startAsync() 是 一 样 的 。 

e stopAsync() :将 停止 所 有 被 管理 的 服务 。 

e addListener : 会 添加 一 个 ServiceManager.Listener ， 在 服务 状态 转 
换 中 会 调用 该 Listener 

e awaitHealthy() :会 等 待 所 有 的 服务 达到 Running 状 态 

e awaitStopped() : 会 等 待 所 有 服务 达到 终止 状态 


检测 类 的 方法 有 : 


e isHealthy() *:** 如 果 所 有 的 服务 处 于 Running 状 态 、 会 返回 True 

e servicesByState() : 以 状态 为 索引 返回 当前 所 有 服务 的 快照 

e startupTimes() :返回 一 个 Map 对 象 ， 记 录 被 管理 的 服务 启动 的 耗 时 、 以 
毫秒 为 单位 ， 同 时 Map 默 认 按 启动 时 间 排 序 。 


我 们 建议 整个 服务 的 生命 周期 都 能 通过 ServiceManager 来 管理 ， 不 过 即使 状态 转换 
是 通过 其 ee ee 例如 : 当 一 1 
服务 不 是 通过 startAsync() 、 其 他 机 制 启动 时 ，listeners 仍然 可 以 被 正常 调用 、 
awaitHealthy() 也 能 够 正常 ° ServiceManager 唯一 强制 的 要 求 是 当 其 被 创建 时 
所 有 的 服务 必须 处 于 New 状 态 。 


附 : TestCase、 也 可 以 作为 练习 Demo 


ServiceTest 
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package com.google.common.util.concurrent; 


import static com.google.common.util.concurrent.Service.State.FA 
ILED; 

import static com.google.common.util.concurrent.Service.State.NE 
W; 

import static com.google.common.util.concurrent.Service.State.RU 
NNING; 

import static com.google.common.util.concurrent.Service.State.ST 
ARTING; 

import static com.google.common.util.concurrent.Service.State.ST 
OPPING; 

import static com.google.common.util.concurrent.Service.State.TE 
RMINATED; 


import junit.framework.TestCase; 


JERR 
* Unit tests for {@link Service} 


‘ays 
public class ServiceTest extends TestCase { 


/** Assert on the comparison ordering of the State enum since we 
guarantee it. */ 

public void testStateOrdering() { 

// List every valid (direct) state transition. 
assertLessThan(NEW, STARTING); 

assertLessThan(NEW, TERMINATED); 


assertLessThan(STARTING, RUNNING); 
assertLessThan(STARTING, STOPPING); 
assertLessThan(STARTING, FAILED); 


assertLessThan(RUNNING, STOPPING); 
assertLessThan(RUNNING, FAILED); 


assertLessThan(STOPPING, FAILED); 
assertLessThan(STOPPING, TERMINATED); 


} 


private static <T extends Comparable<? super T>> void assertLes 
sThan(T a, T b) { 

if (a.compareTo(b) >= 0) { 

fail(String.format("Expected %s to be less than %s", a, b)); 

} 

} 

} 
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package com.google.common.util.concurrent; 
import static org.truthO.Truth.ASSERT; 
import com.google.common.collect.Lists; 
import junit.framework.TestCase; 


import java.util.List; 

import java.util.concurrent.Executor; 

import java.util.concurrent.TimeUnit; 

import java.util.concurrent.TimeoutException; 


JERS 
* Tests for {@link AbstractIdleService}. 
= 
* @author Chris Nokleberg 
* @author Ben Yu 
Hf 
public class AbstractIdleServiceTest extends TestCase { 


// Functional tests using real thread. We only verify publicly v 
isible state. 

// Interaction assertions are done by the single-threaded unit 
tests. 


public static class FunctionalTest extends TestCase { 


private static class DefaultService extends AbstractIdleService 
{ 

@Override protected void startUp() throws Exception {} 
@Override protected void shutDown() throws Exception {} 


} 


public void testServiceStartStop() throws Exception { 
AbstractIdleService service = new DefaultService(); 
service.startAsync().awaitRunning(); 
assertEquals(Service.State.RUNNING, service.state()); 
service.stopAsync().awaitTerminated(); 
assertEquals(Service.State. TERMINATED, service.state()); 
} 


public void testStart_failed() throws Exception { 

final Exception exception = new Exception("deliberate"); 
AbstractIdleService service = new DefaultService() { 
@Override protected void startUp() throws Exception { 
throw exception; 

} 

}; 

try { 


service.startAsync().awaitRunning(); 
fail(); 

} catch (RuntimeException e) { 
assertSame(exception, e.getCause()); 


} 


assertEquals(Service.State.FAILED, service.state()); 


} 


public void testStop_failed() throws Exception { 

final Exception exception = new Exception("deliberate"); 
AbstractIdleService service = new DefaultService() { 
@Override protected void shutDown() throws Exception { 
throw exception; 

} 

}; 

service.startAsync().awaitRunning(); 

try { 

service.stopAsync().awaitTerminated(); 

fail(); 

} catch (RuntimeException e) { 

assertSame(exception, e.getCause()); 

} 

assertEquals(Service.State. FAILED, service.state()); 

} 

} 


public void testStart() { 

TestService service = new TestService(); 

assertEquals(0, service.startUpCalled); 
service.startAsync().awaitRunning(); 

assertEquals(1, service.startUpCalled); 
assertEquals(Service.State.RUNNING, service.state()); 

ASSERT. that(service.transitionStates).has().exactly(Service.Sta 
te.STARTING).inOrder(); 


} 


public void testStart_failed() { 

final Exception exception = new Exception("deliberate"); 
TestService service = new TestService() { 

@Override protected void startUp() throws Exception { 
super.startUp(); 

throw exception; 

} 

}; 

assertEquals(0, service.startUpCalled); 

try { 

service.startAsync().awaitRunning(); 

fail(); 

} catch (RuntimeException e) { 

assertSame(exception, e.getCause()); 


assertEquals(1, service.startUpCalled); 
assertEquals(Service.State. FAILED, service.state()); 


ASSERT. that(service.transitionStates).has().exactly(Service.Sta 
te.STARTING).inOrder(); 


} 


public void testStop_withoutStart() { 

TestService service = new TestService(); 
service.stopAsync().awaitTerminated(); 

assertEquals(0, service.startUpCalled); 

assertEquals(0, service.shutDownCalled) ; 
assertEquals(Service.State.TERMINATED, service.state()); 
ASSERT. that(service.transitionStates).isEmpty(); 


} 


public void testStop_afterStart() { 

TestService service = new TestService(); 
service.startAsync().awaitRunning(); 

assertEquals(1, service.startUpCalled); 

assertEquals(0, service.shutDownCalled) ; 
service.stopAsync().awaitTerminated(); 

assertEquals(1, service.startUpCalled); 

assertEquals(1, service.shutDownCalled) ; 
assertEquals(Service.State. TERMINATED, service.state()); 
ASSERT. that(service.transitionStates) 
.has().exactly(Service.State.STARTING, Service.State.STOPPING). 
inOrder(); 


} 


public void testStop_failed() { 

final Exception exception = new Exception("deliberate"); 
TestService service = new TestService() { 

@Override protected void shutDown() throws Exception { 
super.shutDown(); 

throw exception; 

} 

}; 

service.startAsync().awaitRunning(); 

assertEquals(1, service.startUpCalled); 
assertEquals(0, service.shutDownCalled) ; 

try { 

service.stopAsync().awaitTerminated(); 

fail(); 

} catch (RuntimeException e) { 

assertSame(exception, e.getCause()); 

} 

assertEquals(1, service.startUpCalled); 
assertEquals(1, service.shutDownCalled); 
assertEquals(Service.State.FAILED, service.state()); 
ASSERT. that(service.transitionStates) 
.has().exactly(Service.State.STARTING, Service.State.STOPPING). 
inOrder(); 


} 


public void testServiceToString() { 


AbstractIdleService service = new TestService(); 
assertEquals("TestService [NEW]", service.toString()); 
service.startAsync().awaitRunning(); 
assertEquals("TestService [RUNNING]", service.toString()); 
service.stopAsync().awaitTerminated(); 
assertEquals("TestService [TERMINATED]", service.toString()); 
} 


public void testTimeout() throws Exception { 

// Create a service whose executor will never run its commands 
Service service = new TestService() { 

@Override protected Executor executor() { 

return new Executor() { 

@Override public void execute(Runnable command) {} 

}; 

} 

}; 

try { 

service.startAsync().awaitRunning(1, TimeUnit.MILLISECONDS); 
fail("Expected timeout"); 

} catch (TimeoutException e) { 

ASSERT. that(e.getMessage()).contains(Service.State.STARTING.toS 
ie 


} 


private static class TestService extends AbstractIdleService { 
int startUpCalled = 0; 

int shutDownCalled = 0; 

final List<State> transitionStates = Lists.newArrayList(); 


@Override protected void startUp() throws Exception { 
assertEquals(0, startUpCalled); 
assertEquals(0, shutDownCalled); 
startUpCalled++; 
assertEquals(State.STARTING, state()); 


} 


@Override protected void shutDown() throws Exception { 
assertEquals(1, startUpCalled); 
assertEquals(0, shutDownCalled); 
shutDownCalled++; 
assertEquals(State.STOPPING, state()); 
} 


@Override protected Executor executor() { 
transitionStates.add(state()); 
return MoreExecutors.sameThreadExecutor(); 
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package com.google.common.util.concurrent; 


import com.google.common.util.concurrent.AbstractScheduledServic 


e.Scheduler; 


import com.google.common.util.concurrent.Service.State; 


import junit.framework.TestCase; 
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CountDownLatch; 
CyclicBarrier; 
ExecutionException; 
Executors; 

Future, 


. ScheduledExecutorService; 
.ScheduledFuture; 
.ScheduledThreadPoolExecutor; 
.TimeUnit; 

concurrent. 
concurrent. 


atomic.AtomicBoolean; 
atomic .AtomicInteger; 


{@link AbstractScheduledService}. 


* @author Luke Sandberg 
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public class AbstractScheduledServiceTest extends TestCase { 


volatile Scheduler configuration = Scheduler .newFixedDelaySchedu 
le(@, 10, TimeUnit .MILLISECONDS) ; 
volatile ScheduledFuture<?> future = null; 


volatile boolean atFixedRateCalled = false; 
volatile boolean withFixedDelayCalled = false; 
volatile boolean scheduleCalled = false; 


final ScheduledExecutorService executor = new ScheduledThreadPoo 
lExecutor (10) { 

@Override 

public ScheduledFuture<?> schedulewithFixedDelay(Runnable comma 
nd, long initialDelay, 

long delay, TimeUnit unit) { 

return future = super.schedulewithFixedDelay(command, initialDe 
lay, delay, unit); 

} 

}; 


public void testServiceStartStop() throws Exception { 
NullService service = new NullService(); 
service.startAsync().awaitRunning(); 
assertFalse(future.isDone()); 
service.stopAsync().awaitTerminated(); 
assertTrue(future.isCancelled()); 


} 


private class NullService extends AbstractScheduledService { 
@Override protected void runOneIteration() throws Exception {} 
@Override protected Scheduler scheduler() { return configuratio 
mp 

@Override protected ScheduledExecutorService executor() { retur 
n executor; } 


} 


public void testFailOnExceptionFromRun() throws Exception { 
TestService service = new TestService(); 
service.runException = new Exception(); 
service.startAsync().awaitRunning(); 
service.runFirstBarrier.await(); 
service.runSecondBarrier.await(); 

try { 

future.get(); 

fail(); 

} catch (ExecutionException e) { 

// An execution exception holds a runtime exception (from throw 
ables.propogate) that holds our 

// original exception. 

assertEquals(service.runException, e.getCause().getCause()); 


} 


assertEquals(service.state(), Service.State.FAILED); 


} 


public void testFailOnExceptionFromStartUp() { 
TestService service = new TestService(); 
service.startUpException = new Exception(); 

try { 

service.startAsync().awaitRunning(); 

fail(); 

} catch (IllegalStateException e) { 
assertEquals(service.startUpException, e.getCause()); 


assertEquals(0, service.numberOfTimesRunCalled.get()); 
assertEquals(Service.State.FAILED, service.state()); 


} 


public void testFailOnExceptionFromShutDown() throws Exception { 
TestService service = new TestService(); 
service.shutDownException = new Exception(); 
service.startAsync().awaitRunning(); 
service.runFirstBarrier.await(); 

service.stopAsync(); 

service. runSecondBarrier.await(); 

try { 

service.awaitTerminated(); 

fail(); 

} catch (IllegalStateException e) { 
assertEquals(service.shutDownException, e.getCause()); 
} 


assertEquals(Service.State.FAILED, service.state()); 


} 


public void testRunOneIterationCalledMultipleTimes() throws Exce 
ption { 

TestService service = new TestService(); 
service.startAsync().awaitRunning(); 

for (int i = 1; i < 10; i++) { 
service.runFirstBarrier.await(); 

assertEquals(i, service.numberOfTimesRunCalled.get()); 
service.runSecondBarrier.await(); 

} 

service.runFirstBarrier.await(); 

service.stopAsync(); 

service. runSecondBarrier.await(); 
service.stopAsync().awaitTerminated(); 


} 


public void testExecutorOnlyCalledOnce() throws Exception { 
TestService service = new TestService(); 
service.startAsync().awaitRunning(); 

// It should be called once during startup. 

assertEquals(1, service.numberOfTimesExecutorCalled.get()); 
for (int i = 1; i < 10; i++) { 
service.runFirstBarrier.await(); 


assertEquals(i, service.numberOfTimesRunCalled.get()); 
service. runSecondBarrier.await(); 

} 

service.runFirstBarrier.await(); 

service.stopAsync(); 

service. runSecondBarrier.await(); 
service.stopAsync().awaitTerminated(); 

// Only called once overall. 

assertEquals(1, service.numberOfTimesExecutorCalled.get()); 


} 


public void testDefaultExecutorIsShutdownwhenServiceIsStopped() 
throws Exception { 

final CountDownLatch terminationLatch = new CountDownLatch(1); 
AbstractScheduledService service = new AbstractScheduledService 
() í 

volatile ScheduledExecutorService executorService; 

@Override protected void runOneIteration() throws Exception {} 


@Override protected ScheduledExecutorService executor() { 
if (executorService == null) { 
executorService = super.executor(); 
// Add a listener that will be executed after the listener that 
shuts down the executor. 
addListener(new Listener() { 
@Override public void terminated(State from) { 
terminationLatch.countDown(); 
} 
}, MoreExecutors.sameThreadExecutor()); 
} 


return executorService; 


} 


@Override protected Scheduler scheduler() { 
return Scheduler .newFixedDelaySchedule(0, 1, TimeUnit.MILLISECO 
NDS); 


He 


service.startAsync(); 
assertFalse(service.executor().isShutdown()); 
service.awaitRunning(); 

service.stopAsync(); 

terminationLatch.await(); 
assertTrue(service.executor().isShutdown()); 
assertTrue(service.executor().awaitTermination(100, TimeUnit.MI 
LLISECONDS)); 


} 


public void testDefaultExecutorIsShutdownwhenServiceFails() thro 
ws Exception { 

final CountDownLatch failureLatch = new CountDownLatch(1); 
AbstractScheduledService service = new AbstractScheduledService 


Ome 


volatile ScheduledExecutorService executorService; 
@Override protected void runOneIteration() throws Exception {} 


@Override protected void startUp() throws Exception { 
throw new Exception("Failed"); 


} 
@Override protected ScheduledExecutorService executor() { 
if (executorService == null) { 


executorService = super.executor(); 

// Add a listener that will be executed after the listener that 
shuts down the executor. 

addListener(new Listener() { 

@Override public void failed(State from, Throwable failure) { 
failureLatch.countDown(); 


} 


}, MoreExecutors.sameThreadExecutor()),; 


} 


return executorService; 


} 


@Override protected Scheduler scheduler() { 

return Scheduler .newFixedDelaySchedule(0, 1, TimeUnit .MILLISECO 
NDS); 

thr 


try { 
service.startAsync().awaitRunning(); 


fail("Expected service to fail during startup"); 

} catch (IllegalStateException expected) {} 
failureLatch.await(); 
assertTrue(service.executor().isShutdown()); 
assertTrue(service.executor().awaitTermination(100, TimeUnit.MI 
LLISECONDS)); 


} 


public void testSchedulerOnlyCalledOnce() throws Exception { 
TestService service = new TestService(); 
service.startAsync().awaitRunning(); 

// It should be called once during startup. 

assertEquals(1, service.numberOfTimesSchedulerCalled.get()); 
for (int i = 1; i < 10; i++) { 
service.runFirstBarrier.await(); 

assertEquals(i, service.numberOfTimesRunCalled.get()); 
service. runSecondBarrier.await(); 

} 

service.runFirstBarrier.await(); 

service.stopAsync(); 

service. runSecondBarrier.await(); 

service.awaitTerminated(); 

// Only called once overall. 

assertEquals(1, service.numberOfTimesSchedulerCalled.get()); 


} 


private class TestService extends AbstractScheduledService { 
CyclicBarrier runFirstBarrier = new CyclicBarrier(2); 
CyclicBarrier runSecondBarrier = new CyclicBarrier(2); 


volatile boolean startUpCalled = false; 

volatile boolean shutDownCalled = false; 

AtomicInteger numberOfTimesRunCalled = new AtomicInteger(0); 
AtomicInteger numberOfTimesExecutorCalled = new AtomicInteger (0 
); 

AtomicInteger numberOfTimesSchedulerCalled = new AtomicInteger ( 
0); 

volatile Exception runException = null; 

volatile Exception startUpException = null; 

volatile Exception shutDownException = null; 


@Override 
protected void runOneIteration() throws Exception { 
assertTrue(startUpCalled) ; 
assertFalse(shutDownCalled) ; 
numberOfTimesRunCalled.incrementAndGet(); 
assertEquals(State.RUNNING, state()); 
runFirstBarrier.await(); 
runSecondBarrier.await(); 
if (runException != null) { 
throw runException; 
} 
} 


@Override 
protected void startUp() throws Exception { 
assertFalse(startUpCalled); 
assertFalse(shutDownCalled) ; 
startUpCalled = true; 
assertEquals(State.STARTING, state()); 
if (startUpException != null) { 
throw startUpException; 
} 
} 


@Override 
protected void shutDown() throws Exception { 
assertTrue(startUpCalled) ; 
assertFalse(shutDownCalled) ; 
shutDownCalled = true; 
if (shutDownException != null) { 
throw shutDownException; 
} 
} 


@Override 
protected ScheduledExecutorService executor() { 
numberOfTimesExecutorCalled.incrementAndGet(); 


return executor; 


} 


@Override 
protected Scheduler scheduler() { 
numberOfTimesSchedulerCalled.incrementAndGet(); 
return configuration; 
} 
} 


public static class SchedulerTest extends TestCase { 

// These constants are arbitrary and just used to make sure tha 
t the correct method is called 

// with the correct parameters. 

private static final int initialDelay = 10; 

private static final int delay = 20; 

private static final TimeUnit unit = TimeUnit.MILLISECONDS; 


// Unique runnable object used for comparison. 

final Runnable testRunnable = new Runnable() {@Override public 
void run() {}}; 

boolean called = false; 


private void assertSingleCallwithCorrectParameters(Runnable comm 
and, long initialDelay, 

long delay, TimeUnit unit) { 

assertFalse(called); // only called once. 

called = true; 

assertEquals(SchedulerTest.initialDelay, initialDelay); 
assertEquals(SchedulerTest.delay, delay); 
assertEquals(SchedulerTest.unit, unit); 
assertEquals(testRunnable, command); 


} 


public void testFixedRateSchedule() { 

Scheduler schedule = Scheduler.newFixedRateSchedule(initialDela 
y, delay, unit); 

schedule.schedule(null, new ScheduledThreadPoolExecutor(1) { 
@Override 

public ScheduledFuture<?> scheduleAtFixedRate(Runnable command, 
long initialDelay, 

long period, TimeUnit unit) { 
assertSingleCallwithCorrectParameters(command, initialDelay, de 
lay, unit); 

return null; 

} 

}, testRunnable); 

assertTrue(called); 


} 


public void testFixedDelaySchedule() { 
Scheduler schedule = Scheduler .newFixedDelaySchedule(initialDel 
ay, delay, unit); 


schedule.schedule(null, new ScheduledThreadPoolExecutor(10) { 
@Override 

public ScheduledFuture<?> schedulewithFixedDelay(Runnable comma 
nd, long initialDelay, 

long delay, TimeUnit unit) { 
assertSingleCallwithCorrectParameters(command, initialDelay, de 
lay, unit); 

return null; 

} 

}, testRunnable); 

assertTrue(called); 


} 


private class TestCustomScheduler extends AbstractScheduledServi 
ce.CustomScheduler { 

public AtomicInteger scheduleCounter = new AtomicInteger(0); 
@Override 

protected Schedule getNextSchedule() throws Exception { 
scheduleCounter.incrementAndGet(); 

return new Schedule(0, TimeUnit.SECONDS); 

} 

} 


public void testCustomSchedule_startStop() throws Exception { 
final CyclicBarrier firstBarrier = new CyclicBarrier(2); 
final CyclicBarrier secondBarrier = new CyclicBarrier(2); 
final AtomicBoolean shouldWait = new AtomicBoolean(true); 
Runnable task = new Runnable() { 

@Override public void run() { 

try { 

if (shouldwait.get()) 
firstBarrier.await(); 
secondBarrier.await() 
} 

} catch (Exception e) { 

throw new RuntimeException(e); 

} 

} 

}; 

TestCustomScheduler scheduler = new TestCustomScheduler(); 
Future<?> future = scheduler.schedule(null, Executors.newSchedu 
ledThreadPool(10), task); 

firstBarrier.await(); 

assertEquals(1, scheduler.scheduleCounter.get()); 
secondBarrier.await(); 

firstBarrier.await(); 

assertEquals(2, scheduler.scheduleCounter.get()); 
shouldwait.set(false); 

secondBarrier.await(); 

future.cancel(false); 


} 


{ 


了 


public void testCustomSchedulerServiceStop() throws Exception { 


TestAbstractScheduledCustomService service = new TestAbstractSc 
heduledCustomService(); 

service.startAsync().awaitRunning(); 
service.firstBarrier.await(); 

assertEquals(1, service.numIterations.get()); 
service.stopAsync(); 

service.secondBarrier.await(); 

service.awaitTerminated(); 

// Sleep for a while just to ensure that our task wasn't called 
again. 

Thread.sleep(unit.toMillis(3 * delay)); 

assertEquals(1, service.numIterations.get()); 


} 


public void testBig() throws Exception { 
TestAbstractScheduledCustomService service = new TestAbstractSc 
heduledCustomService() { 

@Override protected Scheduler scheduler() { 

return new AbstractScheduledService.CustomScheduler() { 
@Override 

protected Schedule getNextSchedule() throws Exception { 
// Explicitly yield to increase the probability of a pathologic 
al scheduling. 

Thread. yield(); 

return new Schedule(0, TimeUnit.SECONDS); 

} 

}; 

} 

}; 

service.useBarriers = false; 
service.startAsync().awaitRunning(); 

Thread.sleep(50); 

service.useBarriers = true; 

service.firstBarrier.await(); 

int numIterations = service.numIterations.get(); 
service.stopAsync(); 

service.secondBarrier.await(); 

service.awaitTerminated(); 

assertEquals(numIterations, service.numIterations.get()); 


} 


private static class TestAbstractScheduledCustomService extends 
AbstractScheduledService { 
final AtomicInteger numIterations = new AtomicInteger(0); 
volatile boolean useBarriers = true; 
final CyclicBarrier firstBarrier = new CyclicBarrier(2); 
final CyclicBarrier secondBarrier = new CyclicBarrier(2); 


@Override protected void runOneIteration() throws Exception { 
numIterations.incrementAndGet(); 
if (useBarriers) { 
firstBarrier.await(); 
secondBarrier.await(); 


} 
} 


@Override protected ScheduledExecutorService executor() { 

// use a bunch of threads so that weird overlapping schedules a 
re more likely to happen. 

return Executors.newScheduledThreadPool(10); 


} 


@Override protected void startUp() throws Exception {} 
@Override protected void shutDown() throws Exception {} 


@Override protected Scheduler scheduler() { 

return new CustomScheduler() { 

@Override 

protected Schedule getNextSchedule() throws Exception { 
return new Schedule(delay, unit); 

Jy: 

} 

} 


public void testCustomSchedulerFailure() throws Exception { 
TestFailingCustomScheduledService service = new TestFailingCust 
omScheduledService(); 

service.startAsync().awaitRunning(); 

for (int i = 1; i < 4; i++) { 

service.firstBarrier.await(); 

assertEquals(i, service.numIterations.get()); 
service.secondBarrier.await(); 


Thread.sleep(1000); 

try { 

service.stopAsync().awaitTerminated(100, TimeUnit.SECONDS) ; 
fail(); 

} catch (IllegalStateException e) { 
assertEquals(State.FAILED, service.state()); 

} 

} 


private static class TestFailingCustomScheduledService extends A 
bstractScheduledService { 

final AtomicInteger numIterations = new AtomicInteger(0); 

final CyclicBarrier firstBarrier = new CyclicBarrier(2); 

final CyclicBarrier secondBarrier = new CyclicBarrier(2); 


@Override protected void runOneIteration() throws Exception { 
numIterations.incrementAndGet(); 

firstBarrier.await(); 

secondBarrier.await(); 


} 


@Override protected ScheduledExecutorService executor() { 


// use a bunch of threads so that weird overlapping schedules a 
re more likely to happen. 
return Executors.newScheduledtThreadPool(10); 


} 


@Override protected Scheduler scheduler() { 
return new CustomScheduler() { 
@Override 
protected Schedule getNextSchedule() throws Exception { 
if (numIterations.get() > 2) { 
throw new IllegalStateException("Failed"); 
} 
return new Schedule(delay, unit); 
th; 
} 
} 
} 
} 
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package com.google.common.util.concurrent; 


import static java.lang.Thread.currentThread; 
import static java.util.concurrent.TimeUnit .SECONDS; 


import com.google.common.collect.ImmutableList; 


import com.google.common.collect.Iterables; 

import com.google.common.collect.Lists; 

import com.google.common.util.concurrent.Service.Listener; 
import com.google.common.util.concurrent.Service.State; 


import junit.framework.TestCase; 


import java.lang.Thread.UncaughtExceptionHandler; 
import java.util.List; 

import java.util.concurrent.CountDownLatch; 

import java.util.concurrent.TimeUnit; 

import java.util.concurrent.atomic.AtomicInteger; 
import java.util.concurrent.atomic.AtomicReference; 


import javax.annotation.concurrent.GuardedBy; 


Vanes, 
* Unit test for {@link AbstractService}. 
* 
* @author Jesse Wilson 
Wy 
public class AbstractServiceTest extends TestCase { 


private Thread executionThread; 
private Throwable thrownByExecutionThread; 


public void testNoOpServiceStartStop() throws Exception { 
NoOpService service = new NoOpService(); 
RecordingListener listener = RecordingListener.record(service); 


assertEquals(State.NEW, service.state()); 
assertFalse(service.isRunning()); 
assertFalse(service. running); 


service.startAsync(); 
assertEquals(State.RUNNING, service.state()); 
assertTrue(service.isRunning()); 
assertTrue(service.running); 


service.stopAsync(); 
assertEquals(State. TERMINATED, service.state()); 
assertFalse(service.isRunning()); 
assertFalse(service. running); 
assertEquals( 

ImmutableList.of( 

State.STARTING, 

State.RUNNING, 

State.STOPPING, 

State. TERMINATED), 
listener.getStateHistory()); 


} 


public void testNoOpServiceStartAndwaitStopAndwait() throws Exce 


ption { 
NoOpService service = new NoOpService(); 


service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 


service.stopAsync().awaitTerminated(); 
assertEquals(State. TERMINATED, service.state()); 


} 


public void testNoOpServiceStartAsyncAndAwaitStopAsyncAndAwait ( ) 
throws Exception { 
NoOpService service = new NoOpService(); 


service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 


service.stopAsync().awaitTerminated(); 
assertEquals(State. TERMINATED, service.state()); 


} 


public void testNoOpServiceStopIdempotence() throws Exception { 
NoOpService service = new NoOpService(); 

RecordingListener listener = RecordingListener.record(service); 
service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 


service.stopAsync(); 

service.stopAsync(); 

assertEquals(State. TERMINATED, service.state()); 
assertEquals( 

ImmutableList.of( 

State.STARTING, 

State.RUNNING, 

State.STOPPING, 

State. TERMINATED), 

listener.getStateHistory()); 


} 


public void testNoOpServiceStopIdempotenceAfterwWait() throws Exc 
eption { 
NoOpService service = new NoOpService(); 


service.startAsync().awaitRunning(); 


service.stopAsync().awaitTerminated(); 
service.stopAsync(); 
assertEquals(State. TERMINATED, service.state()); 


} 


public void testNoOpServiceStopIdempotenceDoubleWait() throws Ex 
ception { 
NoOpService service = new NoOpService(); 


service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 


service.stopAsync().awaitTerminated(); 
service.stopAsync().awaitTerminated(); 
assertEquals(State. TERMINATED, service.state()); 


} 


public void testNoOpServiceStartStopAndwaitUninterruptible( ) 
throws Exception { 
NoOpService service = new NoOpService(); 


currentThread().interrupt(); 

try { 

service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 


service.stopAsync().awaitTerminated(); 
assertEquals(State. TERMINATED, service.state()); 


assertTrue(currentThread().isInterrupted()); 

} finally { 

Thread.interrupted(); // clear interrupt for future tests 
} 

} 


private static class NoOpService extends AbstractService { 
boolean running = false; 


@Override protected void doStart() { 
assertFalse(running); 
running = true; 
notifyStarted(); 
} 


@Override protected void doStop() { 
assertTrue(running); 
running = false; 
notifyStopped(); 
} 
} 


public void testManualServiceStartStop() throws Exception { 
ManualSwitchedService service = new ManualSwitchedService(); 
RecordingListener listener = RecordingListener.record(service); 


service.startAsync(); 
assertEquals(State.STARTING, service.state()); 
assertFalse(service.isRunning()); 
assertTrue(service.doStartCalled); 


service.notifyStarted(); // usually this would be invoked by ano 


ther thread 
assertEquals(State.RUNNING, service.state()); 
assertTrue(service.isRunning()); 


service.stopAsync(); 
assertEquals(State.STOPPING, service.state()); 
assertFalse(service.isRunning()); 
assertTrue(service.doStopCalled) ; 


service.notifyStopped(); // usually this would be invoked by ano 
ther thread 

assertEquals(State. TERMINATED, service.state()); 
assertFalse(service.isRunning()); 

assertEquals ( 

ImmutableList.of( 

State.STARTING, 

State.RUNNING, 

State.STOPPING, 

State. TERMINATED), 

listener.getStateHistory()); 


} 


public void testManualServiceNotifyStoppedwhileRunning() throws 
Exception { 

ManualSwitchedService service = new ManualSwitchedService(); 
RecordingListener listener = RecordingListener.record(service); 


service.startAsync(); 

service.notifyStarted(); 
service.notifyStopped(); 

assertEquals(State. TERMINATED, service.state()); 
assertFalse(service.isRunning()); 
assertFalse(service.doStopCalled) ; 


assertEquals( 
ImmutableList. of ( 
State.STARTING, 
State.RUNNING, 

State. TERMINATED), 

listener .getStateHistory()); 


} 


public void testManualServiceStopwhileStarting() throws Exceptio 
nt 

ManualSwitchedService service = new ManualSwitchedService(); 
RecordingListener listener = RecordingListener.record(service); 


service.startAsync(); 
assertEquals(State.STARTING, service.state()); 
assertFalse(service.isRunning()); 
assertTrue(service.doStartCalled); 


service.stopAsync(); 
assertEquals(State.STOPPING, service.state()); 
assertFalse(service.isRunning()); 
assertFalse(service.doStopCalled); 


service.notifyStarted(); 
assertEquals(State.STOPPING, service.state()); 
assertFalse(service.isRunning()); 
assertTrue(service.doStopCalled) ; 


service.notifyStopped(); 
assertEquals(State. TERMINATED, service.state()); 
assertFalse(service.isRunning()); 
assertEquals( 
ImmutableList.of( 
State.STARTING, 
State.STOPPING, 
State. TERMINATED), 
listener.getStateHistory()); 


} 


er 

* This tests for a bug where if {@link Service#stopAsync()} was 
called while the service was 

* {@link State#STARTING} more than once, the {@link Listener#st 
opping(State)} callback would get 

* called multiple times. 
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public void testManualServiceStopMultipleTimeswhileStarting() t 
hrows Exception { 

ManualSwitchedService service = new ManualSwitchedService(); 
final AtomicInteger stopppingCount = new AtomicInteger(); 
service.addListener(new Listener() { 

@Override public void stopping(State from) { 
stopppingCount.incrementAndGet(); 


}, MoreExecutors.sameThreadExecutor()); 


service.startAsync(); 
service.stopAsync(); 

assertEquals(1, stopppingCount.get()); 
service.stopAsync(); 

assertEquals(1, stopppingCount.get()); 
} 


public void testManualServiceStopwhileNew() throws Exception { 
ManualSwitchedService service = new ManualSwitchedService(); 
RecordingListener listener = RecordingListener.record(service); 


service.stopAsync(); 
assertEquals(State.TERMINATED, service.state()); 
assertFalse(service.isRunning()); 
assertFalse(service.doStartCalled); 


assertFalse(service.doStopCalled); 
assertEquals(ImmutableList.of(State. TERMINATED), listener.getSt 
ateHistory()); 


public void testManualServiceFailwhileStarting() throws Exceptio 
nt 

ManualSwitchedService service = new ManualSwitchedService(); 
RecordingListener listener = RecordingListener.record(service); 
service.startAsync(); 

service.notifyFailed(EXCEPTION) ; 
assertEquals(ImmutableList.of(State.STARTING, State.FAILED), li 
stener.getStateHistory()); 


} 


public void testManualServiceFailWhileRunning() throws Exception 
{ 

ManualSwitchedService service = new ManualSwitchedService(); 
RecordingListener listener = RecordingListener.record(service); 
service.startAsync(); 

service.notifyStarted(); 

service.notifyFailed(EXCEPTION) ; 
assertEquals(ImmutableList.of(State.STARTING, State.RUNNING, St 
ate.FAILED), 

listener.getStateHistory()); 


} 


public void testManualServiceFailwhileStopping() throws Exceptio 
nt 

ManualSwitchedService service = new ManualSwitchedService(); 
RecordingListener listener = RecordingListener.record(service); 
service.startAsync(); 

service.notifyStarted()/; 

service.stopAsync(); 

service.notifyFailed(EXCEPTION) ; 
assertEquals(ImmutableList.of(State.STARTING, State.RUNNING, St 
ate.STOPPING, State.FAILED), 

listener.getStateHistory()); 


} 


public void testManualServiceUnrequestedStop() { 
ManualSwitchedService service = new ManualSwitchedService(); 


service.startAsync(); 


service.notifyStarted(); 
assertEquals(State.RUNNING, service.state()); 
assertTrue(service.isRunning()); 
assertFalse(service.doStopCalled); 


service.notifyStopped(); 
assertEquals(State. TERMINATED, service.state()); 
assertFalse(service.isRunning()); 


assertFalse(service.doStopCalled); 


} 


as 

* The user of this service should call {@link #notifyStarted} a 
nd {@link 

* #notifyStopped} after calling {@link #startAsync} and {@link 
#stopAsync}. 

a 

private static class ManualSwitchedService extends AbstractServ 
ice { 

boolean doStartCalled = false; 

boolean doStopCalled = false; 


@Override protected void doStart() { 
assertFalse(doStartCalled); 
doStartCalled = true; 


} 


@Override protected void doStop() { 
assertFalse(doStopCalled) ; 
doStopCalled = true; 

} 
} 


public void testAwaitTerminated() throws Exception { 
final NoOpService service = new NoOpService(); 
Thread waiter = new Thread() { 

@Override public void run() { 
service.awaitTerminated(); 

} 

}; 

waiter.start(); 
service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 
service.stopAsync(); 

waiter.join(100); // ensure that the await in the other thread 
is triggered 

assertFalse(waiter.isAlive()); 


} 


public void testAwaitTerminated_FailedService() throws Exception 
{ 

final ManualSwitchedService service = new ManualSwitchedService 
(); 

final AtomicReference<Throwable> exception = Atomics.newReferen 
ce(); 

Thread waiter = new Thread() { 

@Override public void run() { 

try { 

service.awaitTerminated(); 

fail("Expected an IllegalStateException"); 

} catch (Throwable t) { 


exception.set(t); 

} 

} 

}; 

waiter.start(); 

service.startAsync(); 

service.notifyStarted(); 

assertEquals(State.RUNNING, service.state()); 
service.notifyFailed(EXCEPTION) ; 
assertEquals(State.FAILED, service.state()); 

waiter .join(100); 

assertFalse(waiter.isAlive()); 
assertTrue(exception.get() instanceof IllegalStateException) ; 
assertEquals(EXCEPTION, exception.get().getCause()); 


} 


public void testThreadedServiceStartAndwaitStopAndwait() throws 
Throwable { 
ThreadedService service = new ThreadedService(); 
RecordingListener listener = RecordingListener.record(service); 
service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 


service.awaitRunChecks(); 


service.stopAsync().awaitTerminated(); 
assertEquals(State. TERMINATED, service.state()); 


throwIfSet(thrownByExecutionThread) ; 
assertEquals( 

ImmutableList.of( 

State.STARTING, 

State.RUNNING, 

State.STOPPING, 

State. TERMINATED), 
listener.getStateHistory()); 


} 


public void testThreadedServiceStopIdempotence() throws Throwabl 


et 


ThreadedService service = new ThreadedService(); 


service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 


service.awaitRunChecks()j; 
service.stopAsync(); 
service.stopAsync().awaitTerminated(); 


assertEquals(State. TERMINATED, service.state()); 


throwIfSet(thrownByExecutionThread) ; 
} 


public void testThreadedServiceStopIdempotenceAfterWait() 
throws Throwable { 
ThreadedService service = new ThreadedService(); 


service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 


service.awaitRunChecks()j; 


service.stopAsync().awaitTerminated(); 
service.stopAsync(); 
assertEquals(State. TERMINATED, service.state()); 


executionThread.join(); 


throwIfSet(thrownByExecutionThread) ; 
} 


public void testThreadedServiceStopIdempotenceDoubleWait() 
throws Throwable { 
ThreadedService service = new ThreadedService(); 


service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 


service.awaitRunChecks(); 


service.stopAsync().awaitTerminated(); 
service.stopAsync().awaitTerminated(); 
assertEquals(State. TERMINATED, service.state()); 


throwIfSet(thrownByExecutionThread) ; 
} 


public void testManualServiceFailureIdempotence() { 
ManualSwitchedService service = new ManualSwitchedService(); 
RecordingListener.record(service); 
service.startAsync(); 

service.notifyFailed(new Exception("1")); 
service.notifyFailed(new Exception("2")); 
assertEquals("1", service.failureCause().getMessage()); 
try { 

service.awaitRunning(); 

fail(); 

} catch (IllegalStateException e) { 

assertEquals("1", e.getCause().getMessage()); 

} 

} 


private class ThreadedService extends AbstractService { 
final CountDownLatch hasConfirmedIsRunning = new CountDownLatch 


(1); 


Vas 
* The main test thread tries to stop() the service shortly afte 


* confirming that it is running. Meanwhile, the service itself 
is trying 

* to confirm that it is running. If the main thread's stop() ca 
11 happens 

* before it has the chance, the test will fail. To avoid this, 
the main 

* thread calls this method, which waits until the service has p 
erformed 

* its own "running" check. 

a 

void awaitRunChecks() throws InterruptedException { 
assertTrue("Service thread hasn't finished its checks. " 


+ "Exception status (possibly stale): " + thrownByExecutionThre 
ad, 

hasConfirmedIsRunning.await(10, SECONDS)); 

} 


@Override protected void doStart() { 
assertEquals(State.STARTING, state()); 
invokeOnExecutionThreadForTest(new Runnable() { 
@Override public void run() { 
assertEquals(State.STARTING, state()); 
notifyStarted(); 
assertEquals(State.RUNNING, state()); 
hasConfirmedIsRunning.countDown(); 

} 
}); 
} 


@Override protected void doStop() { 
assertEquals(State.STOPPING, state()); 
invokeOnExecutionThreadForTest(new Runnable() { 
@Override public void run() { 
assertEquals(State.STOPPING, state()); 
notifyStopped(); 
assertEquals(State. TERMINATED, state()); 
} 

H); 
} 
} 


private void invokeOnExecutionThreadForTest(Runnable runnable) { 
executionThread = new Thread(runnable); 
executionThread.setUncaughtExceptionHandler(new UncaughtExcepti 
onHandler() { 

@Override 

public void uncaughtException(Thread thread, Throwable e) { 
thrownByExecutionThread = e; 


} 


J); 


executionThread.start(); 


} 


private static void throwIfSet(Throwable t) throws Throwable { 
if (t != null) { 

throw t; 

} 

} 


public void testStopUnstartedService() throws Exception { 
NoOpService service = new NoOpService(); 
RecordingListener listener = RecordingListener.record(service); 


service.stopAsync(); 
assertEquals(State. TERMINATED, service.state()); 


try { 
service.startAsync(); 


fail(); 

} catch (IllegalStateException expected) {} 

assertEquals(State. TERMINATED, Iterables.getOnlyElement(listene 
r.getStateHistory())); 


} 


public void testFailingServiceStartAndwait() throws Exception { 
StartFailingService service = new StartFailingService(); 
RecordingListener listener = RecordingListener.record(service); 


try { 
service.startAsync().awaitRunning(); 


fail(); 

} catch (IllegalStateException e) { 
assertEquals(EXCEPTION, service. failureCause()); 
assertEquals(EXCEPTION, e.getCause()); 

} 

assertEquals( 

ImmutableList.of( 

State.STARTING, 

State.FAILED), 

listener .getStateHistory()); 


} 


public void testFailingServiceStopAndWait_stopFailing() throws E 

xception { 
StopFailingService service 
RecordingListener listener 


new StopFailingService(); 
RecordingListener.record(service); 


service.startAsync().awaitRunning(); 
try { 
service.stopAsync().awaitTerminated(); 
fail(); 

} catch (IllegalStateException e) { 


assertEquals(EXCEPTION, service.failureCause()); 
assertEquals(EXCEPTION, e.getCause()); 


assertEquals( 
ImmutableList.of( 
State.STARTING, 
State.RUNNING, 
State.STOPPING, 
State.FAILED), 
listener.getStateHistory()); 


} 
public void testFailingServiceStopAndWait_runFailing() throws Ex 
ception { 


RunFailingService service = new RunFailingService(); 
RecordingListener listener = RecordingListener.record(service); 


service.startAsync(); 
try { 
service.awaitRunning(); 
fail(); 
} catch (IllegalStateException e) { 
assertEquals(EXCEPTION, service.failureCause()); 
assertEquals(EXCEPTION, e.getCause()); 
} 
assertEquals( 
ImmutableList.of( 
State.STARTING, 
State.RUNNING, 
State.FAILED), 
listener.getStateHistory()); 


} 


public void testThrowingServiceStartAndwait() throws Exception { 
StartThrowingService service = new StartThrowingService(); 
RecordingListener listener = RecordingListener.record(service); 


try { 
service.startAsync().awaitRunning(); 


fail(); 

} catch (IllegalStateException e) { 
assertEquals(service.exception, service. failureCause()); 
assertEquals(service.exception, e.getCause()); 

} 

assertEquals( 

ImmutableList.of( 

State.STARTING, 

State.FAILED), 

listener .getStateHistory()); 


} 


public void testThrowingServiceStopAndwait_stopThrowing() throws 
Exception { 


StopThrowingService service = new StopThrowingService(); 
RecordingListener listener = RecordingListener.record(service); 


service.startAsync().awaitRunning(); 

try { 

service.stopAsync().awaitTerminated(); 

fail(); 

} catch (IllegalStateException e) { 
assertEquals(service.exception, service.failurecCause()); 
assertEquals(service.exception, e.getCause()); 


assertEquals( 
ImmutableList.of( 
State.STARTING, 
State.RUNNING, 
State.STOPPING, 
State.FAILED), 

listener .getStateHistory()); 


} 


public void testThrowingServiceStopAndWait_runThrowing() throws 
Exception { 

RunThrowingService service = new RunThrowingService(); 
RecordingListener listener = RecordingListener.record(service); 


service.startAsync(); 

try { 

service.awaitTerminated(); 

fail(); 

} catch (IllegalStateException e) { 
assertEquals(service.exception, service.failureCause()); 
assertEquals(service.exception, e.getCause()); 
} 

assertEquals( 

ImmutableList.of( 

State.STARTING, 

State.RUNNING, 

State.FAILED), 

listener.getStateHistory()); 


} 


public void testFailureCause_throwsIfNotFailed() { 
StopFailingService service = new StopFailingService(); 
try { 

service. failureCause(); 

fail(); 

} catch (IllegalStateException e) { 

// expected 

} 

service.startAsync().awaitRunning(); 

try { 

service.failureCause(); 

fail(); 


} catch (IllegalStateException e) { 
// expected 
} 


try { 
service.stopAsync().awaitTerminated(); 


fail(); 

} catch (IllegalStateException e) { 
assertEquals(EXCEPTION, service.failureCause()); 
assertEquals(EXCEPTION, e.getCause()); 

} 

} 


public void testAddListenerAfterFailureDoesntCauseDeadlock() thr 
ows InterruptedException { 

final StartFailingService service = new StartFailingService(); 
service.startAsync(); 

assertEquals(State.FAILED, service.state()); 
service.addListener(new RecordingListener(service), MoreExecuto 
rs.sameThreadExecutor()); 

Thread thread = new Thread() { 

@Override public void run() { 

// Internally stopAsync() grabs a lock, this could be any such 
method on AbstractService. 

service.stopAsync(); 

} 

}; 

thread.start(); 

thread.join(100); 

assertFalse(thread + " is deadlocked", thread.isAlive()); 


} 


public void testListenerDoesntDeadlockOnStartAndWaitFromRunning( 
) throws Exception { 

final NoOpThreadedService service = new NoOpThreadedService(); 
service.addListener(new Listener() { 

@Override public void running() { 

service.awaitRunning(); 

} 

}, MoreExecutors.sameThreadExecutor()); 
service.startAsync().awaitRunning(10, TimeUnit.MILLISECONDS); 
service.stopAsync(); 


} 


public void testListenerDoesntDeadlockOnStopAndWaitFromTerminate 
d() throws Exception { 

final NoOpThreadedService service = new NoOpThreadedService(); 
service.addListener(new Listener() { 

@Override public void terminated(State from) { 
service.stopAsync().awaitTerminated(); 

} 

}, MoreExecutors.sameThreadExecutor()); 
service.startAsync().awaitRunning(); 


Thread thread = new Thread() { 

@Override public void run() { 
service.stopAsync().awaitTerminated(); 

} 

}; 

thread.start(); 

thread. join(100); 

assertFalse(thread + " is deadlocked", thread.isAlive()); 


} 


private static class NoOpThreadedService extends AbstractExecuti 
onThreadService { 

final CountDownLatch latch = new CountDownLatch(1); 

@Override protected void run() throws Exception { 
latch.await(); 

} 

@Override protected void triggerShutdown() { 

latch.countDown(); 

} 

} 


private static class StartFailingService extends AbstractService 
{ 

@Override protected void doStart() { 

notifyFailed(EXCEPTION); 

} 


@Override protected void doStop() { 
fail(); 
} 
} 


private static class RunFailingService extends AbstractService { 
@Override protected void doStart() { 

notifyStarted(); 

notifyFailed(EXCEPTION) ; 

} 


@Override protected void doStop() { 
fail(); 
} 
} 


private static class StopFailingService extends AbstractService 
{ 

@Override protected void doStart() { 

notifyStarted(); 


} 


@Override protected void doStop() { 
notifyFailed(EXCEPTION); 
} 
} 


private static class StartThrowingService extends AbstractServic 


et 


final RuntimeException exception = new RuntimeException("deliber 
ate"); 


@Override protected void doStart() { 
throw exception; 


} 


@Override protected void doStop() { 
fail(); 
} 
} 


private static class RunThrowingService extends AbstractService 


{ 


final RuntimeException exception = new RuntimeException("deliber 
ate"); 


@Override protected void doStart() { 
notifyStarted(); 
throw exception; 


} 


@Override protected void doStop() { 
fail(); 

} 

} 


private static class StopThrowingService extends AbstractService 


{ 


final RuntimeException exception = new RuntimeException("deliber 
ate"); 


@Override protected void doStart() { 
notifyStarted(); 


} 


@Override protected void doStop() { 
throw exception; 
} 
} 


private static class RecordingListener extends Listener { 

static RecordingListener record(Service service) { 
RecordingListener listener = new RecordingListener (service); 
service.addListener(listener, MoreExecutors.sameThreadExecutor ( 


) ) ， 


return listener; 


} 


final Service service; 


RecordingListener(Service service) { 
this.service = service; 


} 


@GuardedBy( "this" ) 
final List<State> stateHistory = Lists.newArrayList(); 
final CountDownLatch completionLatch = new CountDownLatch(1)j; 


ImmutableList<State> getStateHistory() throws Exception { 
completionLatch.await(); 

synchronized (this) { 

return ImmutableList.copyOf(stateHistory); 

} 

} 


@Override public synchronized void starting() { 
assertTrue(stateHistory.isEmpty()); 
assertNotSame(State.NEW, service.state()); 
stateHistory.add(State.STARTING) ) 


} 


@Override public synchronized void running() { 
assertEquals(State.STARTING, Iterables.getOnlyElement(stateHist 
ory)); 
stateHistory.add(State.RUNNING); 
service.awaitRunning(); 
assertNotSame(State.STARTING, service.state()); 


} 


@Override public synchronized void stopping(State from) { 
assertEquals(from, Iterables.getLast(stateHistory) ); 
stateHistory.add(State.STOPPING) ; 
if (from == State.STARTING) { 
try { 
service.awaitRunning(); 
fail(); 

} catch (IllegalStateException expected) { 
assertNull(expected.getCause()); 
assertTrue(expected.getMessage( ) .equals( 

"Expected the service to be RUNNING, but was STOPPING")); 
} 

} 


assertNotSame(from, service.state()); 


} 


@Override public synchronized void terminated(State from) { 
assertEquals(from, Iterables.getLast(stateHistory, State.NEW)); 
stateHistory.add(State.TERMINATED); 
assertEquals(State.TERMINATED, service.state()); 


if (from == State.NEW) { 

try { 

service.awaitRunning(); 

fail(); 

} catch (IllegalStateException expected) { 
assertNull(expected.getCause()); 
assertTrue(expected.getMessage( ) .equals( 

"Expected the service to be RUNNING, but was TERMINATED" )); 
} 

} 


completionLatch.countDown(); 


} 


@Override public synchronized void failed(State from, Throwable 
failure) { 

assertEquals(from, Iterables.getLast(stateHistory) ); 
stateHistory.add(State.FAILED); 
assertEquals(State.FAILED, service.state()); 
assertEquals(failure, service.failureCause()); 
if (from == State.STARTING) { 

try { 

service.awaitRunning(); 

fail(); 

} catch (IllegalStateException e) { 
assertEquals(failure, e.getCause()); 

} 

} 

try { 

service.awaitTerminated(); 

fail(); 

} catch (IllegalStateException e) { 
assertEquals(failure, e.getCause()); 

} 

completionLatch.countDown(); 

} 

} 


public void testNotifyStartedwhenNotStarting() { 
AbstractService service = new DefaultService(); 
try { 

service.notifyStarted(); 

fail(); 

} catch (IllegalStateException expected) {} 

} 


public void testNotifyStoppedwhenNotRunning() { 
AbstractService service = new DefaultService(); 
try { 

service.notifyStopped(); 

fail(); 

} catch (IllegalStateException expected) {} 

} 


public void testNotifyFailedwhenNotStarted() { 
AbstractService service = new DefaultService(); 
try { 

service.notifyFailed(new Exception()); 

fail(); 

} catch (IllegalStateException expected) {} 

} 


public void testNotifyFailedwhenTerminated() { 
NoOpService service = new NoOpService(); 
service.startAsync().awaitRunning(); 
service.stopAsync().awaitTerminated(); 

try { 

service.notifyFailed(new Exception()); 
fail(); 

} catch (IllegalStateException expected) {} 

} 


private static class DefaultService extends AbstractService { 
@Override protected void doStart() {} 
@Override protected void doStop() {} 


} 


private static final Exception EXCEPTION = new Exception(); 
} 
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public class ServiceManagerTest extends TestCase { 


private static class NoOpService extends AbstractService { 
@Override protected void doStart() { 
notifyStarted(); 


} 


@Override protected void doStop() { 
notifyStopped(); 


} 
} 


Mw 


* A NoOp service that will delay the startup and shutdown notif 
ication for a configurable amount 
* of time. 


of 


private static class NoOpDelayedSerivce extends NoOpService { 
private long delay; 


public NoOpDelayedSerivce(long delay) { 
this.delay = delay; 
} 


@Override protected void doStart() { 

new Thread() { 

@Override public void run() { 
Uninterruptibles.sleepUninterruptibly(delay, TimeUnit .MILLISECO 
NDS); 

notifyStarted(); 

} 

}.start(); 


} 


@Override protected void doStop() { 

new Thread() { 

@Override public void run() { 
Uninterruptibles.sleepUninterruptibly(delay, TimeUnit .MILLISECO 
NDS); 

notifyStopped(); 

} 

}.start(); 

} 

} 


private static class FailStartService extends NoOpService { 
@Override protected void doStart() { 

notifyFailed(new IllegalStateException("failed")); 

} 

} 


private static class FailRunService extends NoOpService { 
@Override protected void doStart() { 

super .doStart(); 

notifyFailed(new IllegalStateException("failed")); 

} 

} 


private static class FailStopService extends NoOpService { 
@Override protected void doStop() { 

notifyFailed(new IllegalStateException("failed")); 

} 

} 


public void testServiceStartupTimes() { 

Service a = new NoOpDelayedSerivce(150); 

Service b = new NoOpDelayedSerivce(353); 

ServiceManager serviceManager = new ServiceManager(asList(a, b) 
); 

serviceManager .startAsync().awaitHealthy(); 
ImmutableMap<Service, Long> StartupTimes = serviceManager.start 
upTimes(); 


assertEquals(2, startupTimes.size()); 
assertTrue(startupTimes.get(a) >= 150); 
assertTrue(startupTimes.get(b) >= 353); 
} 


public void testServiceStartStop() { 

Service a = new NoOpService(); 

Service b = new NoOpService(); 

ServiceManager manager = new ServiceManager(asList(a, b)); 
RecordingListener listener = new RecordingListener(); 
manager .addListener(listener); 

assertState(manager, Service.State.NEW, a, b); 
assertFalse(manager.isHealthy()); 

manager .startAsync().awaitHealthy(); 
assertState(manager, Service.State.RUNNING, a, b); 
assertTrue(manager.isHealthy()); 
assertTrue(listener.healthyCalled); 
assertFalse(listener.stoppedCalled) ; 
assertTrue(listener.failedServices.isEmpty()); 
manager .stopAsync().awaitStopped(); 
assertState(manager, Service.State.TERMINATED, a, b); 
assertFalse(manager.isHealthy()); 
assertTrue(listener.stoppedCalled); 
assertTrue(listener.failedServices.isEmpty()); 


} 


public void testFailStart() throws Exception { 


Service a = new NoOpService(); 
Service b = new FailStartService(); 
Service c = new NoOpService(); 
Service d = new FailStartService(); 


Service e = new NoOpService(); 

ServiceManager manager = new ServiceManager(asList(a, b, c, 
e)); 

RecordingListener listener = new RecordingListener(); 
manager .addListener (listener); 

assertState(manager, Service.State.NEW, a, b, c, d, e); 
try { 

manager .startAsync( ).awaitHealthy(); 

fail(); 

} catch (IllegalStateException expected) { 

} 

assertFalse(listener.healthyCalled) ; 
assertState(manager, Service.State.RUNNING, a, c, e); 


assertEquals(ImmutableSet.of(b, d), listener.failedServices); 


assertState(manager, Service.State.FAILED, b, d); 
assertFalse(manager.isHealthy()); 


manager .stopAsync().awaitStopped(); 
assertFalse(manager.isHealthy()); 
assertFalse(listener.healthyCalled) ; 
assertTrue(listener.stoppedCalled); 


} 


public void testFailRun() throws Exception { 
Service a = new NoOpService(); 
Service b = new FailRunService(); 


ServiceManager manager = new ServiceManager(asList(a, b)); 


RecordingListener listener = new RecordingListener(); 
manager .addListener(listener); 

assertState(manager, Service.State.NEW, a, b); 

try { 

manager .startAsync().awaitHealthy(); 

fail(); 

} catch (IllegalStateException expected) { 


} 
assertTrue(listener.healthyCalled); 


assertEquals(ImmutableSet.of(b), listener .failedServices); 


manager .stopAsync().awaitStopped(); 
assertState(manager, Service.State.FAILED, b); 
assertState(manager, Service.State.TERMINATED, a); 


assertTrue(listener.stoppedCalled); 


} 


public void testFailStop() throws Exception { 

Service a = new NoOpService(); 

Service b = new FailStopService(); 

Service c = new NoOpService(); 

ServiceManager manager = new ServiceManager(asList(a, b, 
RecordingListener listener = new RecordingListener(); 
manager .addListener(listener); 


manager .startAsync().awaitHealthy(); 
assertTrue(listener.healthyCalled); 
assertFalse(listener.stoppedCalled) ; 
manager .stopAsync().awaitStopped(); 


assertTrue(listener.stoppedCalled) ; 


c)); 


assertEquals(ImmutableSet.of(b), listener .failedServices); 


assertState(manager, Service.State.FAILED, b); 
assertState(manager, Service.State.TERMINATED, a, C); 


} 


public void testToString() throws Exception { 
Service a = new NoOpService(); 
Service b = new FailStartService(); 


ServiceManager manager = new ServiceManager(asList(a, b)); 


String toString = manager.toString(); 
assertTrue(toString.contains("NoOpService")); 
assertTrue(toString.contains("FailStartService") ); 


} 


public void testTimeouts() throws Exception { 
Service a = new NoOpDelayedSerivce(50); 


ServiceManager manager = new ServiceManager(asList(a)); 
manager.startAsync(); 

try { 

manager .awaitHealthy(1, TimeUnit.MILLISECONDS) ; 

fail(); 

} catch (TimeoutException expected) { 

} 

manager .awaitHealthy(100, TimeUnit.MILLISECONDS); // no excepti 
on thrown 


manager .stopAsync(); 

try { 

manager .awaitStopped(1, TimeUnit.MILLISECONDS); 

fail(); 

} catch (TimeoutException expected) { 

} 

manager .awaitStopped(100, TimeUnit.MILLISECONDS); // no excepti 
on thrown 


} 
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* This covers a case where if the last service to stop failed t 
hen the stopped callback would 

* never be called. 

a 

public void testSingleFailedServiceCallsStopped() { 
Service a = new FailStartService(); 

ServiceManager manager = new ServiceManager(asList(a)); 
RecordingListener listener = new RecordingListener(); 
manager .addListener(listener); 

try { 

manager .startAsync().awaitHealthy(); 

fail(); 

} catch (IllegalStateException expected) { 

} 


assertTrue(listener.stoppedCalled); 


} 


JENE 

* This covers a bug where listener.healthy would get called whe 
n a single service failed during 

* startup (it occurred in more complicated cases also). 
S 

public void testFailStart_singleServiceCallsHealthy() { 
Service a = new FailStartService(); 

ServiceManager manager = new ServiceManager(asList(a)); 
RecordingListener listener = new RecordingListener(); 
manager .addListener (listener); 

try { 

manager .startAsync().awaitHealthy(); 

fail(); 

} catch (IllegalStateException expected) { 

} 


assertFalse(listener.healthyCalled) ; 
} 


We 

* This covers a bug where if a listener was installed that woul 
d stop the manager if any service 

* fails and something failed during startup before service.star 
t was called on all the services, 

* then awaitStopped would deadlock due to an IllegalStateExcept 
ion that was thrown when trying to 

* stop the timer(!). 

i 

public void testFailStart_stopOthers() throws TimeoutException 
{ 

Service a = new FailStartService(); 

Service b = new NoOpService(); 

final ServiceManager manager = new ServiceManager(asList(a, b)) 
了 

manager .addListener(new Listener() { 

@Override public void failure(Service service) { 

manager .stopAsync(); 

}}); 

manager.startAsync(); 

manager .awaitStopped(10, TimeUnit .MILLISECONDS) ; 


} 


private static void assertState( 

ServiceManager manager, Service.State state, Service... service 
s) { 

Collection<Service> managerServices = manager .servicesByState() 
.get(state); 

for (Service service : services) { 
assertEquals(service.toString(), state, service.state()); 
assertEquals(service.toString(), service.isRunning(), state == 
Service.State.RUNNING); 

assertTrue(managerServices + " should contain " + service, mana 
gerServices.contains(service)); 

} 

} 


Vanes 

* This is for covering a case where the ServiceManager would be 
have strangely if constructed 

* with no service under management. Listeners would never fire 
because the ServiceManager was 

* healthy and stopped at the same time. This test ensures that 
listeners fire and isHealthy 

* makes sense. 

tif 

public void testEmptyServiceManager() { 

Logger logger = Logger.getLogger(ServiceManager.class.getName( ) 


| 
logger .setLevel(Level.FINEST); 


TestLogHandler logHandler = new TestLogHandler(); 

logger .addHandler(logHandler ) ; 

ServiceManager manager = new ServiceManager(Arrays.<Service>asL 
ist()); 

RecordingListener listener = new RecordingListener(); 

manager .addListener(listener, MoreExecutors.sameThreadExecutor ( 
)); 

manager .startAsync().awaitHealthy(); 
assertTrue(manager.isHealthy()); 
assertTrue(listener.healthyCalled); 
assertFalse(listener.stoppedCalled) ; 
assertTrue(listener.failedServices.isEmpty()); 

manager .stopAsync().awaitStopped(); 
assertFalse(manager.isHealthy()); 
assertTrue(listener.stoppedCalled); 
assertTrue(listener.failedServices.isEmpty()); 

// check that our NoOpService is not directly observable via an 
y of the inspection methods or 

// via logging. 

assertEquals("ServiceManager{services=[]}", manager.toString() ) 
了 

assertTrue(manager.servicesByState().isEmpty()); 
assertTrue(manager.startupTimes().isEmpty()); 

Formatter logFormatter = new Formatter() { 
@Override public String format(LogRecord record) { 

return formatMessage(record); 

} 

}; 

for (LogRecord record : logHandler.getStoredLogRecords()) { 
assertFalse(logFormatter.format(record).contains("NoOpService") 
i 

} 
} 
JEE 

* This is for a case where a long running Listener using the sa 
meThreadListener could deadlock 

* another thread calling stopAsync(). 

z 


) 


public void testListenerDeadlock() throws InterruptedException { 
final CountDownLatch failEnter = new CountDownLatch(1); 

Service failRunService = new AbstractService() { 

@Override protected void doStart() { 

new Thread() { 

@Override public void run() { 

notifyStarted(); 

notifyFailed(new Exception("boom")); 


} 
}.start(); 


} 
@Override protected void doStop() { 
notifyStopped(); 


} 

}; 

final ServiceManager manager = new ServiceManager ( 

Arrays.asList(failRunService, new NoOpService())); 

manager .addListener(new ServiceManager.Listener() { 

@Override public void failure(Service service) { 

failEnter.countDown(); 

// block forever! 

Uninterruptibles.awaitUninterruptibly(new CountDownLatch(1)); 

} 

}, MoreExecutors.sameThreadExecutor()); 

// We do not call awaitHealthy because, due to races, that meth 
od may throw an exception. But 

// we really just want to wait for the thread to be in the fail 
ure callback so we wait for that 

// explicitly instead. 

manager.startAsync(); 

failEnter.await(); 

assertFalse("State should be updated before calling listeners", 

manager .isHealthy()); 

// now we want to stop the services. 

Thread stoppingThread = new Thread() { 

@Override public void run() { 

manager .stopAsync().awaitStopped(); 

} 

}; 

stoppingThread.start(); 

// this should be super fast since the only non stopped service 

is a NoOpService 

stoppingThread.join(1000) ; 

assertFalse("stopAsync has deadlocked!.", stoppingThread.isAliv 
e()); 

} 


DA 

* Catches a bug where when constructing a service manager faile 
d, later interactions with the 

* service could cause IllegalStateExceptions inside the partial 
ly constructed ServiceManager. 

* This ISE wouldn't actually bubble up but would get logged by 
ExecutionQueue. This obfuscated 

* the original error (which was not constructing ServiceManager 
correctly). 

is 

public void testPartiallyConstructedManager() { 

Logger logger = Logger.getLogger("global"); 

logger .setLevel(Level.FINEST); 

TestLogHandler logHandler = new TestLogHandler(); 

logger .addHandler(logHandler ); 

NoOpService service = new NoOpService(); 

service.startAsync(); 


try { 
new ServiceManager (Arrays.asList(service) ); 


fail(); 

} catch (IllegalArgumentException expected) {} 
service.stopAsync(); 

// Nothing was logged! 

assertEquals(0, logHandler.getStoredLogRecords().size()); 


} 


public void testPartiallyConstructedManager_transitionAfterAddLi 
stenerBeforeStateIsReady() { 

// The implementation of this test is pretty sensitive to the i 
mplementation ![:(](http://ifeve.com/wp-includes/images/smilies/ 
frownie.png) but we want to 

// ensure that if weird things happen during construction then 
we get exceptions. 

final NoOpService servicei = new NoOpService(); 

// This service will start service1 when addListener is called. 

This simulates servicei being 

// started asynchronously. 

Service service2 = new Service() { 

final NoOpService delegate = new NoOpService(); 

@Override public final void addListener(Listener listener, Exec 
utor executor) { 

service1.startAsync(); 

delegate.addListener(listener, executor); 

} 

// Delegates from here on down 

@Override public final Service startAsync() { 

return delegate.startAsync(); 


} 


@Override public final Service stopAsync() { 
return delegate.stopAsync(); 


} 


@Override public final ListenableFuture<State> start() { 
return delegate.start(); 


} 


@Override public final ListenableFuture<State> stop() { 
return delegate.stop(); 


} 


@Override public State startAndwait() { 
return delegate.startAndwait(); 


} 


@Override public State stopAndwait() { 
return delegate.stopAndwait(); 


} 


@Override public final void awaitRunning() { 
delegate.awaitRunning(); 


} 


@Override public final void awaitRunning(long timeout, TimeUnit 
unit ) 

throws TimeoutException { 

delegate.awaitRunning(timeout, unit); 


} 


@Override public final void awaitTerminated() { 
delegate.awaitTerminated(); 


} 


@Override public final void awaitTerminated(long timeout, TimeUn 
it unit) 

throws TimeoutException { 

delegate.awaitTerminated(timeout, unit); 


} 


@Override public final boolean isRunning() { 
return delegate.isRunning(); 


} 


@Override public final State state() { 
return delegate.state(); 


} 


@Override public final Throwable failureCause() { 
return delegate. failureCause(); 


new ServiceManager(Arrays.asList(service1, service2)); 

fail(); 

} catch (IllegalArgumentException expected) { 
assertTrue(expected.getMessage().contains("started transitionin 
g asynchronously") ); 

} 

} 


Vas 

* This test is for a case where two Service.Listener callbacks 
for the same service would call 

* transitionService in the wrong order due to a race. Due to th 
e fact that it is a race this 

* test isn't guaranteed to expose the issue, but it is at least 
likely to become flaky if the 

* race sneaks back in, and in this case flaky means something i 
s definitely wrong. 

* 

* <p>Before the bug was fixed this test would fail at least 30% 
of the time. 

i 


public void testTransitionRace() throws TimeoutException { 


for (int k = 0; k < 1000; k++) { 

List<Service> services = Lists.newArrayList(); 

fOr (nt 

services.add(new SnappyShutdownService(i)); 

} 

ServiceManager manager = new ServiceManager (services); 
manager .startAsync().awaitHealthy(); 

manager .stopAsync().awaitStopped(1, TimeUnit.SECONDS); 
} 

} 


We 

* This service will shutdown very quickly after stopAsync is ca 
lled and uses a background thread 

* so that we know that the stopping() listeners will execute on 
a different thread than the 

* terminated() listeners. 

ag 

private static class SnappyShutdownService extends AbstractExec 
utionThreadService { 

final int index; 

final CountDownLatch latch = new CountDownLatch(1); 


SnappyShutdownService(int index) { 
this.index = index; 


} 


@Override protected void run() throws Exception { 
latch. await(); 


} 


@Override protected void triggerShutdown() { 
latch.countDown(); 


} 


@Override protected String serviceName() { 
return this.getClass().getSimpleName() + "[" + index + "]"; 
} 
} 


public void testNulls() { 

ServiceManager manager = new ServiceManager(Arrays.<Service>asL 
ist()); 

new NullPointerTester() 

.setDefault (ServiceManager.Listener.class, new RecordingListene 
r()) 

.testAl1lPublicInstanceMethods(manager ) ; 


} 


private static final class RecordingListener extends ServiceMana 
ger.Listener { 

volatile boolean healthyCalled; 

volatile boolean stoppedCalled; 


final Set<Service> failedServices = Sets.newConcurrentHashSet ( ) 


了 


@Override public void healthy() { 
healthyCalled = true; 


} 


@Override public void stopped() { 
stoppedCalled = true; 


} 


@Override public void failure(Service service) { 
failedServices.add(service); 


<pre> 


6- 字 符 串 处 理 : PB HR MK 


原文 链接 译文 链接 译 者 : 沈 义 扬 ， 校 对 : 丁 一 


Æ 44 4 [Joiner] 


用 分 隔 符 把 字符 串 序 列 连接 起 来 也 可 能 会 遇 上 不 必要 的 麻烦 。 如 果 字 符 串 序列 中 含 
有 null， 那 连接 操作 会 更 难 。Fluent 风 格 的 Joiner 让 连接 字符 串 更 简单 。 


Joiner joiner = Joiner.on("; ").skipNulls(); 
return joiner.join("Harry", null, "Ron", "Hermione"); 


上 述 代码 返回 "Harry; Ron; Hermione”。 另 外 ，useForNull(String) 方 法 可 以 给 定 某 
个 字符 串 来 替换 null， 而 不 像 skipNulls() 方 法 是 直接 忽略 null。 Joiner 也 可 以 用 来 连 
接 对 象 类 型 ， 在 这 种 情况 下 ， 它 会 把 对 象 的 toString() 值 连接 起 来 。 


Joiner.on(",").join(Arrays.asList(1, 5, 7)); // returns "1,5,7" 


警告 : joiner 实 例 总 是 不 可 变 的 。 用 来 定义 joiner 目 标语 义 的 配置 方法 总 会 返回 一 个 
新 的 joiner 实 例 。 这 使 得 joiner 实 例 都 是 线程 安全 的 ， 你 可 以 将 其 定义 为 static final% 


wo 


HT Z [Splitter] 


JDK 内 建 的 字符 串 拆 分 工具 有 一 些 十 怪 的 特性 。 比 如 ，String.split 悄 悄 丢弃 了 尾部 
的 分 隔 符 。 问题 : ",a,,b,”.split(“*,”) 返 回 ? 


{, ls es 
2. null, “a”, null, “b”, null 
3. “a”, null, “b” 

4. “a”, “b” 

5. 以 上 都 不 对 


正确 答案 是 5 : ”， a, "b"。 只 有 尾部 的 空 字符 囊 被 忽略 了 。 Splitter 使 用 令 
人 放心 的 、 直 白 的 流 帕 API 模 式 对 这 些 混乱 的 特性 作 了 完全 的 掌控 。 


Splitter.on(',') 
. trimResults() 
.omitEmptyStrings() 
.Split("foo,bar,, qux"); 


上 述 代码 返回 lterable<String>， 其 中 包含 foo"”、"bar 和 "qux"。Splitter 可 以 被 设置 
为 按照 任何 模式 、 字 符 、 字 符 串 或 字符 匹配 器 拆 分 。 


拆 分 器 工厂 


方法 


Splitter. 


Splitter 


Splitter. 


Splitter. 
Splitter. 


Splitter 


on(char) 


.on(CharMatcher ) 


on(String) 


on(Pattern) 
onPattern(String) 


.fixedLength(int ) 


描述 
按 单 
SF 
符 拆 
分 

R? 
符 匹 
配器 
HT 


按 字 
符 串 
拆 分 


按 正 
则 表 
达 式 
拆 分 


按 固 
定 长 
度 拆 
T: 
最 后 
一 段 
可 能 
比 给 
定 长 
度 
短 ， 
但 不 
会 为 


we 
Te o 
sk 


范例 


Splitter.on(‘;’) 


Splitter.on(CharMatcher.BREAKING 


Splitter.on(“, “) 


Splitter.onPattern(“\r?\n") 


Splitter.fixedLength(3) 


方法 描述 


omitEmptyStrings() 从 结果 中 自动 忽略 空 字符 串 
trimResults() 移 除 结果 字符 事 的 前 导 空 白 和 尾部 空白 


给 定 匹 配器 ， 移 除 结 果 字 符 串 的 前 导 匹 配 字 
符 和 尾部 匹配 字符 


limit (int) 限制 拆 分 出 的 字符 串 数量 


trimResults(CharMatcher ) 


如 果 你 想 要 拆 分 器 返回 List， 只 要 使 用 Lists.newArrayList(splitter.split(string)) 或 类 似 
方法 。 警告 : splitter 实 例 总 是 不 可 变 的 。 用 来 定义 Splitter 目 标语 义 的 配置 方法 总 会 
返回 一 个 新 的 splitter 实 例 。 这 使 得 splitter 实 例 都 是 线程 安全 的 ， 你 可 以 将 其 定义 为 
static final 常 量 。 


字符 匹配 器 [CharMatchen] 


在 以 前 的 Guava 版 本 中 ，StringUtil 类 疯狂 地 膨胀 ， 其 拥有 很 多 处 理 字符 串 的 方法 : 
allAscii ` collapse ` collapseControlChars ` collapseWhitespace ` indexOfChars ` 
lastindexNotOf ` numSharedChars ` removeChars ` removeCrLf ` 

replaceChars ` retainAllChars ` strip ` stripAndCollapse ` stripNonDigits ° 所 有 这 
些 方 法 指向 两 个 概念 上 的 问题 : 


1. 怎么 才 算 匹配 字符 ? 
2. 如 何 处 理 这 些 匹 配 字符 ? 


为 了 收拾 这 个 泥潭 ， 我 们 开发 了 CharMatcher 。 


直观 上 ， 你 可 以 认为 一 个 CharMatcher 实 例 代 表 着 某 一 类 字符 ， 如 数字 或 空白 字 

符 。 事 实 上 来 说 ，CharMatcher 实 例 就 是 对 字符 的 布尔 判断 一 一 CharMatcher 确 实 
也 实现 了 Predicate<Character> 一 一 但 类 似 " 所 有 空白 字符 ”或 "所 有 小 写字 母 "的 需求 
大 普 遍 了 ，Guava 因 此 创建 了 这 一 AP|。 


然而 使 用 CharMatcher 的 好 处 更 在 于 它 提供 了 一 系列 方法 ， 让 你 对 字符 作 特 定 类 型 
的 操作 : 修剪 [trim]、 折 县 [collapse]、 移 除 [remove]、 保 留 [retain] 等 等 。 
CharMatcher 实 例 首 先 代表 概念 1 : 怎么 才 算 匹配 字符 ? 然后 它 还 提供 了 很 多 操作 概 
念 2 : 如 何 处 理 这 些 匹配 字符 ? 这 样 的 设计 使 得 API 复 杂 度 的 线性 增加 可 以 带 来 灵活 
性 和 功能 两 方面 的 增长 。 








String noControl = CharMatcher .JAVA_ISO_CONTROL. removeFrom(Strin 
g); // 移 除 control 字 符 

String theDigits = CharMatcher .DIGIT.retainFrom(string); // 只 保留 
数字 字符 

String spaced = CharMatcher .WHITESPACE.trimAndCollapseFrom(strin 
Q, ' '); 

// 去 除 两 端的 空格 ， 并 把 中 间 的 连续 空格 替换 成 单个 空格 

String noDigits = CharMatcher.JAVA_DIGIT.replaceFrom(string, "*" 
) ; // 用 * 号 替换 所 有 数字 

String lowerAndDigit = CharMatcher.JAVA_DIGIT.or(CharMatcher. .JAV 
A_LOWER_CASE).retainFrom(string); 

// 只 保留 数字 和 人 小 写字 母 


注 : CharMatcher 只 处 理 char 类 型 代表 的 字符 ; 它 不 能 理解 0x10000 到 0x10FFFF 的 
Unicode 增补 字符 。 这 些 逻 辑 字 符 以 代理 对 [surrogate pairs] 的 形式 编码 进 字 符 串 ， 
而 CharMatcher 只 能 将 这 种 逻辑 字符 看 待 成 两 个 独立 的 字符 。 

获取 字符 匹配 器 


CharMatcher 中 的 常量 可 以 满足 大 多 数字 符 匹 配 需求 : 


ANY NONE WHITESPACE 
INVISIBLE DIGIT JAVA_LETTER 
JAVA_LETTER_OR_DIGIT JAVA_ISO_CONTROL JAVA_LOWER_CASE 
ASCII SINGLE_WIDTH 


其 他 获取 字符 匹配 器 的 常见 方法 包括 : 


方法 描述 


A 7K DL He F FF o 4a CharMatcher.anyOf(“aeiou”) & 

anyOf (CharSequence eth tos Se 
ven xh ) 配 小 写 英 语 元 首 

as (cham) 给 定单 一 字符 匹配 。 


Ke ep RE Re š E pa 
inRange(char, char) 给 定 字符 范围 匹配 ， 如 CharMatcher.inRange('a’， 


此 外 ，CharMatcher 还 
有 negate() 、 and(CharMatcher) 和 or(CharMatcher) 方法 。 


使 用 字符 匹配 器 


CharMatcher 提 供 了 多 种 多 样 的 方法 操作 CharSequence 中 的 特定 字符 。 其 中 最 常 
用 的 罗列 如 下 : 


方法 


collapseFrom(CharSequence, char) 


matchesAl1lOf (CharSequence) 
removeFrom(CharSequence) 


retainFrom(CharSequence) 


trimFrom(CharSequence) 


replaceFrom(CharSequence, CharSequence) 


描述 

把 每 组 连续 的 匹配 字符 替换 : 

字符 。 如 

WHITESPACE.collapseFror 
为 单个 空格 。 


测试 是 否 字符 序列 中 的 所 有 : 
匹配 。 


从 字符 序列 中 移 除 所 有 匹配 : 
在 字符 序列 中 保留 匹配 字符 
移 除 字符 序列 的 前 导 匹 配 字 ; 
部 匹配 字符 。 

用 特定 字符 序列 替代 匹配 字 : 


所 有 这 返回 String， 除 了 matchesAllOf 返 回 的 是 boolean。 


字符 集 [Charsets] 
不 要 这 样 做 字符 集 处 理 : 


try { 
bytes = string.getBytes("UTF-8"); 


} catch (UnsupportedEncodingException e) { 


// how can this possibly happen? 
throw new AssertionError(e); 


试 试 这 样 写 : 


bytes = string.getBytes(Charsets.UTF_8); 


ee a a 了 常量 引用 。 尝 试 


使 用 这 些 常 量 ， 而 不 是 通过 名 称 获 取 字 符 集 实例 。 


写 格 式 [CaseFormat] 


CaseFormat# 来 方便 地 在 各 种 ASCII 大 小 写 规 规范 间 转 换 字符 串 一 一 比如 ， 编 程 语 


言 的 命名 规范 。CaseFormat 支 持 的 格式 如 下 


格式 
LOWER_CAMEL 
LOWER_HYPHEN 
LOWER_UNDERSCORE 
UPPER_CAMEL 


UPPER_UNDERSCORE 


CaseFormat 的 用 法 很 直接 : 


lowerCamel 
lower-hyphen 
lower_underscore 
UpperCamel 
UPPER_UNDERSCORE 


CaseFormat.UPPER_UNDERSCORE.to(CaseFormat.LOWER_CAMEL, "CONSTANT 
_NAME")); // returns "constantName" 


我 们 CaseFormat 在 某 些 时 候 尤 其 有 用 ， 比 如 编写 代码 生成 器 的 时 候 。 


7- 原 生 类 型 


原文 链接 译文 链接 EA : 沈 义 扬 ， 校 对 : 丁 一 


概述 


Java 的 原生 类 型 就 是 指 基 本 类 型 : byte、short、int、long、float、double、char 和 
boolean ° 


在 从 Guava 查 找 原生 类 型 方法 之 前 ， 可 以 先 查 查 Arrays 类 ， 或 者 对 应 的 基础 类 型 包 
装 类 ， 如 /nteger。 

原生 类 型 不 能 当 作 对 象 或 泛 型 的 类 型 参数 使 用 ， 这 意味 着 许多 通用 方法 都 不 能 应 用 
于 它们 。Guava 提 供 了 若干 通用 工具 ， 包 括 原生 类 型 数组 与 集合 API 的 交互 ， 原 生 

类 型 和 字 节 数组 的 相互 转换 ， 以 及 对 某 些 原生 类 型 的 无 符号 形式 的 支持 。 


原生 类 型 ”Guava* 工 具 类 (都 在 com.google.common.primitives 包 **) 


byte Bytes , SignedBytes , UnsignedBytes 

short Shorts 

int Ints , UnsignedInteger , UnsignedInts 
long Longs , UnsignedLong , UnsignedLongs 
float Floats 

double Doubles 

char Chars 

boolean Booleans 


Bytes 工 具 类 没有 定义 任何 区 分 有 符号 和 无 符号 字 节 的 方法 ， 而 是 把 它们 都 放 到 了 
SignedBytes 和 UnsignedBytes 工 具 类 中 ， 因 为 字 节 类 型 的 符号 性 比 起 其 它 类 型 要 略 
AKAD BA HE o 


int 和 long 的 无 符号 形式 方法 在 Unsignedlnts 和 UnsignedLongs 类 中 ， 但 由 于 这 两 个 
类 型 的 大 多 数 用 法 都 是 有 符号 的 ，lnts 和 Longs 类 按照 有 符号 形式 处 理 方法 的 输入 参 
数 。 


此 外 ，Guava 为 int 和 long 的 无 符号 形式 提供 了 包装 类 ， 即 Unsignedlnteger 和 
UnsignedLong， 以 帮助 你 使 用 类 型 系统 ， 以 极 小 的 性 能 消耗 对 有 符号 和 无 符号 什 
进行 强制 转换 。 


在 本 章 下 面 描述 的 方法 签名 中 ， 我 们 用 Wrapper 表 示 JDK 包 装 类 ，prim 表 示 原 生 类 
Alo (Prims 表 示 相 应 的 Guava 工 具 类 。 ) 


原生 类 型 数组 工具 


原生 类 型 数组 是 处 理 原生 类 型 集合 的 最 有 效 方式 〈 从 内 存 和 性 能 双方 面 考虑 ) 。 
Guava 为 此 提供 了 许多 工具 方法 。 


方法 签名 


List<Wrapper> asList(prim... 
backingArray) 


prim[] 
toArray(Collection<Wrapper> 
collection) 


prim[] concat(prim[]... arrays) 


boolean contains(prim[] 
array, prim target) 


int indexOf(prim[] array, prim 
target) 


int lastIndexOf(prim[] array, 


prim target) 


prim min(prim... array) 


prim max(prim... array) 


描述 


把 数组 转 为 相应 包 
装 类 的 List 


把 集合 拷贝 为 数 
2 9 和 
collection.toArray() 
一 样 线程 安全 


给 定 值 在 数组 中 首 
次 出 现 处 的 索引 ， 
若 不 包含 此 值 返 
回 -1 


给 定 值 在 数组 最 后 
RIA Ra] > HH 
包含 此 值 返回 -1 


数组 中 最 小 的 值 


数组 中 最 大 的 值 


类 似 方法 


Arrays.asList 


Collection.toArray() 


Iterables.concat 


Collection.contains 


List.indexOf 


List.lastIndexOf 


Collections.min 


Collections.max 


String join(String separator, 把 数组 用 给 定 分 隔 


Joiner.on(separator).join 


prim... array) 符 连 接 为 字符 串 

. 按 字典 序 比 较 原 生 
OPAR orm 类 型 数组 的 Ordering.natural().lexicog 
lexicographicalComparator() Comparator 


* 符 号 无 关 方 法 存在 于 Bytes, Shorts, Ints, Longs, Floats, Doubles, Chars, 
Booleans。 而 Unsignedlnts, UnsignedLongs, SignedBytes, 或 UnsignedBytes 不 存 


* 符 号 相关 方法 存在 于 SignedBytes, UnsignedBytes, Shorts, Ints, Longs, Floats, 
Doubles, Chars, Booleans, Unsignedlnts, UnsignedLongs。 而 Bytes 不 存在 。 


通用 工具 方法 


Guava 为 原生 类 型 提供 了 若干 JDK6 没 有 的 工具 方法 。 但 请 注意 ， 其 中 某 些 方法 已 经 
存在 于 JDK7 中 。 


方法 签名 描述 可 用 性 

1 1 传统 的 Comparatorcompare 方 法 ， 但 针对 
ne 原生 类 型 。JDK7 的 原生 类 型 包装 类 也 提供 。 符号 相关 

这 样 的 方法 

prim 把 给 定 long 值 转 为 某 一 原生 类 型 ， 若 给 定 仅 适 用 于 
checkedCast(long ” 和 值 不 符合 该 原生 类 型 ， 则 抛 出 符号 相关 
value) IllegalArgumentException 的 整 型 * 
Pim ,CU ，， 把 给 定 long 值 转 为 菜 一 原生 类 型 ， 若 给 定 BEAT 
SaturatedCast{long 和 值 不 符合 则 使 用 最 接近 的 原生 类 型 值 P 
value) 的 整 型 


* 这 里 的 整 型 包括 byte, short, int, long。 不 包括 char, boolean, float, 或 double。 


** 译 者 注 : 不 符合 主要 是 指 /ong 值 超出 prim 类 型 的 范围 ， 比 如 过 大 的 /Jong 超出 int 范 


注 : com.google.common.math.DoubleMath 提 供 了 全 入 double 的 方法 ， 支 持 多 种 
会 入 模式 。 相 见 第 12 章 的 " 浮 点 数 运 算 ”。 


字 节 转换 方法 


Guava 提 供 了 若干 方法 ， 用 来 把 原生 类 型 按 大 字 节 序 与 字 节 数组 相互 转换 。 所 有 这 
些 方法 都 是 符号 无 关 的 ， 此 外 Booleans 没 有 提供 任何 下 面 的 方法 。 


方法 或 字段 签名 

int BYTES 

prim 
fromByteArray(bytel] 
bytes) 


prim fromBytes(byte 
b1, ..., byte bk) 


byte[] 
toByteArray(prim 
value) 


无 符号 支持 


描述 
常量 : 表示 该 原生 类型 需要 的 字 节 数 


使 用 字 节 数组 的 前 Prims.BYTES 个 字 节 ， 按 大 字 节 序 返 
回 原生 类 型 值 ; 如 果 bytes.length <= Prims.BYTES ， 
Ja W IAE 

接受 Prims.BYTES 个 字 节 参数 ， 按 大 字 节 序 返回 原生 类 
型 值 


按 大 字 节 序 返回 value 的 字 节 数组 


JDK 原 生 类 型 包装 类 提供 了 针对 有 符号 类 型 的 方法 ， 而 Unsignedlnts 和 
UnsignedLongs 工 具 类 提供 了 相应 的 无 符号 通用 方法 。Unsignedlnts 和 
UnsignedLongs 直 接 处 理 原生 类 型 : 使 用 时 ， 由 你 自己 保证 只 传 入 了 无 符号 类 型 的 


值 。 


此 外 ， 对 int 和 long，Guava 提 供 了 无 符号 包装 类 (Unsignedlnteger 和 
UnsignedLong) ， 来 帮助 你 以 极 小 的 性 能 消耗 ， 对 有 符号 和 无 符号 类 型 进行 强制 


转换 。 


无 符号 通用 工具 方法 


JDK 的 原生 类 型 包装 类 提供 了 有 符号 形式 的 类 似 方法 。 


方法 签名 


int UnsignedInts.parseUnsignedInt(String) long UnsignedLongs.pars 


int UnsignedInts.parseUnsignedInt(String string, int radix) long 


String UnsignedInts.toString(int) String UnsignedLongs.toString(l 


String UnsignedInts.toString(int value, int radix) String Unsigne 


cH 
a 
oh 
cy 
ye 
A% 
(© 
s> 
< 


# 干 方法 ， 让 使 用 和 转换 更 容易 。 
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方法 签名 
UnsignedPrim 
add(UnsignedPrim), 


subtract, multiply, divide, 
remainder 


UnsignedPrim 
valueOf(BigInteger) 


UnsignedPrim 
valueOf(long) 


UnsignedPrim 
asUnsigned(prim value) 


BigInteger 
bigIntegerValue() 


toString(), toString(int 
radix) 


按 给 定 Biglnteger 返 回 无 符号 对 象 ， 若 Biglnteger 
为 负 或 不 匹配 ， 抛 出 IAE 


按 给 定 long 返 回 无 符号 对 象 ， 若 long 为 负 或 不 匹 
配 ， 抛 出 |AE 


把 给 定 的 值 当 作 无 符号 类 型 。 例 如 ， 
UnsignedlntegerasUnsigned(1<<31) 的 值 为 
2<sup>31</sup>, 尽 管 1<<31 当 作 int 时 是 负 的 


用 Biglnteger 返 回 该 无 符号 对 象 的 值 


返回 无 符号 值 的 字符 串 表示 


8- 区 问 


原文 链接 译文 链接 译文 : 沈 义 扬 
范例 


List scores; 
Iterable belowMedian =Iterables.filter(scores, Range.lessThan(med 
ian) ); 


Range validGrades = Range.closed(1i, 12); 
for(int grade : ContiguousSet.create(validGrades, DiscreteDomain 


.integers())) { 


} 


简介 


区 间 ， 有 时 也 称 为 范围 ， 是 特定 域 中 的 凸 性 ( 非 正式 说 法 为 连续 的 或 不 中 断 的 ) 部 
分 。 在 形式 上 上， 加 性 表示 对 a<=b<=c, range.contains(a) 且 range.contains(c) 意 味 着 
range.contains(b) ° 


区 间 可 以 延伸 至 无 限 一 例如 ， 范 围 "x>3" 包 括 任意 大 于 3 的 值 一 也 可 以 被 限制 为 
有 限 ， 如 ”2<=x<5"。Guava 用 更 紧凑 的 方法 表示 范围 ， 有 数学 背景 的 程序 员 对 此 是 
耳熟能详 的 : 


e (a..b) ={x|a<x<b} 
e [a..b] = {x | a <= x <= b} 
e [a..b) = {x |a<=x<b} 
e (a..b] = {x |a<x <=b} 
e (a..t%) = {x |x >a} 

e [a..+%) = {x | x >= a} 

e (-~..b) = {x | x < b} 

e (-~..b] = {x | x <= b} 

e (-%..+%) = 所 有 值 


上 面 的 a D b 称 为 端 点 2 为 了 提高 一 致 性 9 Guava 中 的 Range 要 求 上 端 点 不 能 小 于 下 
端点 。 上 下 端点 有 可 能 是 相等 的 ， 但 要 求 区 间 是 闭 区 间或 半 开 半 闭 区 间 (至 少 有 一 
个 端点 是 包含 在 区 间 中 的 ) 


。[a..a] : 单元 素 区 间 
e [a..a); (a..a] : 空 区 间 ， 但 它们 是 有 效 的 
e (a.a): TARN 





Guava 用 类 型 Range<C> 表 示 区 间 。 所 有 区 间 实 现 都 是 不 可 变 类 型 。 


构建 区 间 

区 间 实 例 可 以 由 Range 类 的 静态 方法 获取 : 
(a..b) open(C, C) 
[a..b] closed(C, C) 
[a..b) closedOpen(C, C) 
(a..b] openClosed(C, C) 
(a..+%) greaterThan(C) 
[a..+°0) atLeast(C) 
(-œ..b) lessThan(C) 
(-œ..b] atMost(C) 
(-co..+co) all() 


Range.closed("left", "right"); // 字 典 序 在 "left" 和 "right" 之 问 的 字符 串 
ABN 
Range.lessThan(4.0); // 严 格 小 于 4.0 的 double 值 


此 外 ， 也 可 以 明确 地 指定 边界 类 型 来 构造 区 间 : 
A JSE N range(C, BoundType, C, BoundType)) 
无 上 界 区 间 : ((a..+o) 或 [a..+%)) downTo(C, BoundType) 
FF IRE | : ((-%..b) 或 (-%..b])  upTo(C, BoundType) 


这 里 的 BoundType 是 一 个 枚 举 类 型 ， 包 含 CLOSED 和 OPEN 两 个 值 。 


Range.downTo(4, boundType);// (a..+%m) 或 [a. .+o)， 取 决 于 boundType 
Range.range(1, CLOSED, 4, OPEN);// [1..4)， 等 同 于 Range.closed0pen 
(1, 4) 


区 间 运 算 
Range 的 基本 运算 是 它 的 contains(C) 方法 ， 和 你 期 望 的 一 样 ， 它 用 来 区 间 判 断 是 否 


包含 某 个 值 。 此 外 ，Range 实 例 也 可 以 当 作 Predicate， 并 且 在 函数 式 编程 中 使 用 
( 译 者 注 : 见 第 4 章 ) 。 任 何 Range 实 例 也 都 支持 containsAll(lterable<? extends 


C>) 方 法 : 


Range.closed(1, 3).contains(2);//return true 

Range.closed(1, 3).contains(4);//return false 
Range.lessThan(5).contains(5); //return false 

Range.closed(1, 4).containsAll(Ints.asList(1, 2, 3)); //return t 
rue 


查询 运算 
Range 类 提供 了 以 下 方法 来 查看 区 间 的 端点 


e hasLowerBound() 和 hasUpperBound() : 判断 区 间 是 否 有 特定 边界 ， 或 是 无 限 
的 3 

e |owerBoundType() 和 upperBoundType() : 返回 区 间 边 界 类 型 ，CLOSED 或 
OPEN ; 如 果 区 间 没 有 对 应 的 边界 ， 抛 出 llegalStateException ; 

e lowerEndpoint() 和 upperEndpoint() : 返回 区 间 的 端点 值 ; 如 果 区 间 没 有 对 应 的 
iu FR > Hu H IllegalStateException ; 

e isEmpty(): 判断 是 否 为 空 区 间 。 


Range.closedOpen(4, 4).isEmpty(); // returns true 
Range.openClosed(4, 4).isEmpty(); // returns true 
Range.closed(4, 4).isEmpty(); // returns false 

Range.open(4, 4).isEmpty(); // Range.open throws IllegalArgument 
Exception 

Range.closed(3, 10).lowerEndpoint(); // returns 3 

Range.open(3, 10).lowerEndpoint(); // returns 3 

Range.closed(3, 10).lowerBoundType(); // returns CLOSED 
Range.open(3, 10).upperBoundType(); // returns OPEN 


关系 运算 
包含 [enclose] 


区 间 之 间 的 最 基本 关系 就 是 包含 [ encloses(Range) ] : 如 果 内 区 间 的 边界 没有 超 
出 外 区 间 的 边界 ， 则 外 区 间 包 人 钨 内 区 间 。 包 含 判 断 的 结果 完全 取决 于 区 间 端 点 的 比 
较 | 


e [3..6] 包含 [4..5] ; 

e (3..6) 包含 (3..6) ; 

e [3..6] 包含 [4..4)， 虽 然后 者 是 空 区 间 ; 
e (3..6] 不 包含 [3..6] ; 

e [4..5] 不 包含 


[3. 
(3. 6)， 虽 然 前 者 包含 了 后 者 的 所 有 值 ， 离散 域 [discrete domains] 
可 以 解决 这 个 问题 ( 见 8.5 节 ) 

e [3..6] 不 包含 (1..1]， 虽 然 前 者 包含 了 后 者 的 所 有 值 。 


包含 是 一 种 偏 序 关系 [partial ordering]。 基 于 包含 关系 的 概念 ，Range 还 提供 了 以 下 
运算 方法 。 
日 连 [isConnected] 


Range ,isConnected(Range) 判断 区 间 有 是否 是 相连 的 。 有 具体 来 党 ，isConnected 
测试 是 否 有 区 间 同 时 包含 于 这 两 个 区 间 ， 这 等 同 于 数学 上 的 定义 "两 个 区 间 的 并 集 是 
连续 集合 的 形式 ”( 空 区 间 的 特殊 情况 除外 ) 。 


相连 是 一 种 自 反 的 [reflexive]、 对 称 的 [symmetric] 关 系 。 


Range.closed(3, 5).isConnected(Range.open(5, 10)); // returns tr 
Range.closed(0, 9).isConnected(Range.closed(3, 4)); // returns t 
Range.closed(0, 5).isConnected(Range.closed(3, 9)); // returns t 
Range.open(3, 5).isConnected(Range.open(5, 10)); // returns fals 


Range.closed(1, 5).isConnected(Range.closed(6, 10)); // returns 


交集 [intersection] 


Range.intersection(Range) 返回 两 个 区 间 的 交集 : 既 包 含 于 第 一 个 区 间 ， 又 
包含 于 另 一 个 区 间 的 最 大 区 间 。 当 且 仅 当 两 个 区 间 是 相连 的 ， 它 们 才 有 交集 。 如 果 
两 个 区 间 没 有 交集 ， 该 方法 将 抛 出 legalArgumentException 。 


z 管 


交集 是 可 互 换 的 [commutative] 、 关 联 的 [associative] 运算 [operation]。 


Range.closed(3, 5).intersection(Range.open(5, 10)); // returns ( 
a ET 9).intersection(Range.closed(3, 4)); // returns 
ao 5).intersection(Range.closed(3, 9)); // returns 
a acerca 5).intersection(Range.open(5, 10)); // throws IAE 
Range.closed(1, 5).intersection(Range.closed(6, 10)); // throws 
IAE 


35 & ï [span] 


Range. span (Range) 返回 "同时 包括 两 个 区 间 的 最 小 区 间 ”， 如 果 两 个 区 间 相 和 连 
那 就 是 它们 的 并 集 。 


span 是 可 互 换 的 [commutative] 、 关 联 的 [associative] 、 闭 合 的 [closed] 运 算 
[operation] ° 


Range.closed(3, 5).span(Range.open(5, 10)); // returns [3, 10) 
Range.closed(0, 9).span(Range.closed(3, 4)); // returns [0, 9] 
Range.closed(0, 5).span(Range.closed(3, 9)); // returns [0, 9] 
Range.open(3, 5).Span(Range.open(5, 10)); // returns (3, 10) 
Range.closed(1, 5).span(Range.closed(6, 10)); // returns [1, 10] 


离散 域 


部 分 (但 不 是 全 部 ) 可 比较 类 型 是 离散 的 ， 即 区 间 的 上 下 边界 都 是 可 枚 举 的 。 

在 Guava 中 ， 用 DiscreteDomain<C> 实 现 类 型 C 的 离散 形式 操作 。 一 个 离散 域 总 是 
代表 某 种 类 型 值 的 全 集 ; 它 不 能 代表 类 似 ” 素 数 "、” 长 度 为 5 的 字符 串 " 或 "午夜 的 时 间 
BA” 3h HE 14 Fy BBR, © 


DiscreteDomain 提 供 的 离散 域 实例 包括 : 


类 型 离散 域 
Integer integers() 
Long longs() 


一 旦 获取 了 DiscreteDomain 实 例 ， 你 就 可 以 使 用 下 面 的 Range 运 算 方法 : 


e ContiguousSet.create(range, domain) : 用 ImmutableSortedSet<C> 形 式 表 示 
Range<C> 中 符合 离散 域 定义 的 元 素 ， 并 增加 一 些 额外 操作 一 一 译 者 注 : 实际 
返回 ImmutableSortedSet 的 子 类 ContiguousSet。 (对 无 限 区 间 不 起 作用 ， 
除非 类 型 C 本 身 是 有 限 的 ， 比 如 int 就 是 可 枚 举 的 ) 

e canonical(domain) : 把 离散 域 转 为 区 间 的 "规范 形式 ”。 如 果 
ContiguousSet.create(a, domain).equals(ContiguousSet.create(b, domain)) 并 
且 !a.isEmpty()， 则 有 a.canonical(domain).equals(b.canonical(domain))。 (这 
并 不 意味 着 a.equals(b)) 





ImmutableSortedSet set = ContigousSet.create(Range.open(1, 5), i 
screteDomain.integers()); 

//set 包 含 [2，3，4] 

ContiguousSet.create(Range.greaterThan(0), DiscreteDomain.intege 
rs()); 


//set&@e[1, 2, ..., Integer.MAX_VALUE] 


i£% > ContiguousSet.create#} ZA AHMET REPRE > MERA T set Akg A 
间 视 图 。 


你 自己 的 离散 域 


你 可 以 创建 自己 的 离散 域 ， 但 必须 记 住 DiscreteDomain 契 约 的 几 个 重要 方面 。 


© 一 个 离散 域 总 是 代表 某 种 类 型 值 的 全 集 ; 它 不 能 代表 类 似 " 素 数 " 或 "长 度 为 5 的 
字符 串 ” 这 样 的 局 部 域 。 所 以 举例 来 说 ， 你 无 法 构造 一 个 DiscreteDomain 以 表 
示 精 确 到 秒 的 JODA DateTime 日 期 集合 : 因为 那 将 无 法 包含 JODA DateTime 的 
所 有 值 ° 

e DiscreteDomain 可 能 是 无 限 的 一 一 比如 Biglnteger DiscreteDomain。 这 种 情况 
下 ， 你 应 当 用 minValue() 和 maxValue() 的 默认 实现 ， 它 们 会 抛 出 
NoSuchElementException。 但 Guava 禁 止 把 无 限 区 间 传 入 
ContiguousSet.create 一 一 译 者 注 : 那 明 显得 不 到 一 个 可 枚 举 的 集合 。 





如 果 我 需要 一 个 Comparator 呢 ? 


我 们 想 要 在 Range 的 可 用 性 与 AP| 复 杂 性 之 间 找 到 特定 的 平衡 ， 这 部 分 导致 了 我 们 
没有 提供 基于 Comparator 的 接口 : 我 们 不 需要 操心 区 间 是 怎样 基于 不 同 
Comparator 互 动 的 ; 所 有 API 签 名 都 是 简单 明确 的 ; 这 样 更 好 。 


另 一 方面 ， 如 果 你 需要 任意 Comparator， 可 以 按 下 列 其 中 一 项 来 做 : 


e 使 用 通用 的 Predicate 接 口 ， 而 不 是 Range 类 。 (Range 实 现 了 Predicate 接 口 ， 
此 可 以 用 Predicates.compose(range, function) 获 取 Predicate 实 例 ) 
o 使 用 包装 类 以 定义 期 望 的 排序 。 


译 者 注 : 实际 上 Range 规 定 元 素 类 型 必须 是 Comparable， 这 已 经 满足 了 大 多 数 需 
求 。 如 果 需 要 自 定义 特殊 的 比较 逻辑 ， 可 以 用 Predicates.compose(range, function) 
组 合 比 较 的 function。 
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原文 链接 译文 链接 译 者 : 沈 义 扬 


` + x2 ` 广大 s ~> 
FD Fue FAP 


Guava 使 用 术语 ? 流 ” 来 表示 可 关闭 的 ， 并 且 在 底层 资源 中 有 位 置 状 态 的 MO 数据 流 。 
术语 " 字 节 流 " 指 的 是 InputStream 或 OutputStream ，” 字 符 流 " 指 的 是 Reader 或 
Writer (虽然 他 们 的 接口 Readable 和 Appendable 被 更 多 地 用 于 方法 参数 ) 。 相 应 
的 工具 方法 分 别 在 ByteStreams 和 CharStreams 中 。 


大 多 数 Guava 流 工具 一 次 处 理 一 个 完整 的 流 vit ? 并 且 / 或 者 为 了 效率 自 己 处 理 缓冲 。 还 
要 注意 到 ， ， 接受 流 为 参数 的 Guava 方 法 不 会 关闭 这 个 流 。 : 关闭 流 的 职责 页 H 通 常 属 于 打 
开 流 的 代码 块 。 


其 中 的 一 些 工具 方法 列举 如 下 : 


ByteStreams CharStreams 

byte[] toByteArray(InputStream) String toString(Readable) 
N/A List&lt;String&gt; readLi 
long copy(InputStream, OutputStream) long copy(Readable, Appen 
void readFully(InputStream, byte[]) N/A 

void skipFully(InputStream, long) void skipFully(Reader, lo 
OutputStream nullOutputStream( ) Writer nullwriter() 


关于 InputSupplier 和 OutputSupplier 有 要 注意 : 


在 ByteStreams、CharStreams 以 及 com.google.common.io 包 中 的 一 些 其 他 类 中 ， 
某 些 方法 仍然 在 使 用 InputSupplier 和 OutputSupplier 接 口 。 这 两 个 借口 和 相关 的 方 
法 是 不 推荐 使 用 的 : 它们 已 经 被 下 面 描述 的 source 和 sink 类 型 取代 了 ， 并 且 最 终 会 
被 移 除 。 


We. Ay IE 


通常 我 们 都 会 创建 MO 工具 方法 ， 这 样 可 以 避免 在 做 基础 运算 时 总 是 直接 和 流 打 区 
道 。 例 如 ，Guava 有 Files. toByteArray(File) 和 Files.write(File, byte[]) ° 然而 ， 流 工 
具 方 法 的 创建 经 常 最 终 导致 散落 各 处 的 相似 方法 ， 每 个 方法 读 取 不 同类 型 的 源 


或 写 入 不 同类 型 的 汇 [sink]。 例如，Guava 中 的 Resources. toByteArray(URL) 和 
Files.toByteArray(File) 做 了 同样 的 事情 ， 只 不 过 数据 源 一 个 是 URL ， 一 个 是 文件 。 


为 了 解决 这 个 问题 ，Guava 有 一 系列 关于 源 与 汇 的 抽象 。 源 或 汇 指 某 个 你 知道 如 何 
从 中 打开 流 的 资源 ， 比 如 File 或 URL 。 源 是 可 读 的 ， 汇 是 可 写 的 。 此 外 ， 源 与 汇 按 
照 字 节 和 字符 划分 类 型 。 


字 节 字符 
读 ByteSource CharSource 
写 ByteSink CharSink 


源 与 汇 API 的 好 处 是 它们 提供 了 通用 的 一 组 操作 。 上 比如， 一 旦 你 把 数据 源 包装 成 了 
ByteSource， 无 论 它 原先 的 类 型 是 什么 ， 你 都 得 到 了 一 组 按 字 节 操作 的 方法 。 


创建 源 与 汇 
Guava 提 供 了 若干 源 与 汇 的 实现 : 

F 字符 
Files.asByteSource(File) Files.asCharSource(Fi 
Files.asByteSink(File, FileWriteMode...) Files.asCharSink(File 
Resources.asByteSource(URL) Resources.asCharSourc 
ByteSource.wrap(byte[ ]) CharSource.wrap(CharS 
ByteSource.concat (ByteSource. .. ) CharSource.concat(Cha 
ByteSource.slice(long, long) N/A 

N/A ByteSource.asCharSour 

N/A ByteSink.asCharSink(C 


此 外 ， 你 也 可 以 继承 这 些 类 ， 以 创建 新 的 实现 。 


注 : 把 已 经 打开 的 流 (比如 InputStream ) 包装 为 源 或 汇 听 起 来 是 很 有 诱惑 力 的 ， 
但 是 应 该 避免 这 样 做 。 源 与 汇 的 实现 应 该 在 每 次 openStream() 方 法 被 调用 时 都 创建 
一 个 新 的 流 。 始 终 创建 新 的 流 可 以 让 源 或 汇 管理 流 的 整个 生命 周期 ， 并 且 让 多 次 调 
用 openStream() 返 回 的 流 都 是 可 用 的 。 此 外 ， 如 果 你 在 创建 源 或 汇 之 前 创建 了 流 ， 
你 不 得 不 在 异常 的 时 候 自己 保证 关闭 流 ， 这 压根 就 违背 了 发 挥 源 与 汇 API 优 点 的 初 
# 


使 用 源 与 汇 
一 旦 有 了 源 与 汇 的 实例 ， 就 可 以 进行 若干 读 写 操作 。 
通用 操作 


所 有 源 与 汇 都 有 一 些 方法 用 于 打开 新 的 流 用 于 读 或 写 。 默 认 情 况 下 ， 其 他 源 与 汇 操 
作 都 是 先 用 这 些 方法 打开 流 ， 然 后 做 一 些 读 或 写 ， 最 后 保证 流 被 正确 地 关闭 了 。 这 
些 方法 列举 如 下 : 


e openStream() : 根据 源 与 汇 的 类 型 ， 返 回 InputStream、OutputStream、 
Reader 或 者 Writer。 

e openBufferedStream() : 根据 源 与 汇 的 类 型 ， 返 回 InputStream、 
OutputStream、BufferedReader 或 者 BufferedWriter。 返 回 的 流 保证 在 必要 情 
况 下 做 了 缓冲 。 例 如 ， 从 字 节 数组 读数 据 的 源 就 没有 必要 再 在 内 存 中 作 缓 冲 ， 
这 就 是 为 什么 该 方法 针对 字 节 源 不 返回 BufferedlnputStream。 字 符 源 属于 例外 
情况 ， 它 一 定 返 回 BufferedReader， 因 为 BufferedReader 中 才 有 readLine() 方 
法 。 


源 操作 
字 节 源 字符 源 
byte[] read() String read() 
N/A ImmutableList&lt;String&gt; 
N/A String readFirstLine() 
long copyTo(ByteSink ) long copyTo(CharSink) 
long copyTo(OutputStream) long copyTo(Appendable) 
long size() (in bytes) N/A 
boolean isEmpty() boolean isEmpty() 


boolean contentEquals(ByteSource) N/A 


HashCode hash(HashFunction) N/A 
汇 操作 
FPX 字符 汇 
void write(byte[]) void write(CharSequence) 
long writeFrom( InputStream) long writeFrom(Readable) 
N/A void writeLines(Iterable&lt;? exte 
N/A void writeLines(Iterable&lt;? exte 


范例 


//Read the lines of a UTF-8 text file 
ImmutableList<String> lines = Files.asCharSource(file, Charsets. 
UTF_8).readLines(); 
//Count distinct word occurrences in a file 
Multiset<String> wordOccurrences = HashMultiset.create( 
Splitter.on(CharMatcher .WHITESPACE ) 

.trimResults() 

.omitEmptyStrings() 

.Split(Files.asCharSource(file, Charsets.UTF_8).read 
())); 


//SHA-1 a file 
HashCode hash = Files.asByteSource(file).hash(Hashing.shai()); 


//Copy the data from a URL to a file 
Resources.asByteSource(url).copyTo(Files.asByteSink(file) ); 


文件 操作 

除了 创建 文件 源 和 文件 的 方法 ，Files 类 还 包含 了 若干 你 可 能 感 兴趣 的 便利 方法 。 
createParentDirs(File) 必要 时 为 文件 创建 父 目录 
getFileExtension(String) 返回 给 定 路 径 所 表示 文件 的 扩展 名 
getNameWithoutExtension(String) 返回 去 除了 扩展 名 的 文件 名 


规范 文件 路 径 ， 并 不 总 是 与 文件 系 


simplifyPath(String) 统一 致 ， 请 仔细 测试 


fileTreeTraverser() 返回 TreeTraverser 用 于 遍历 文件 树 
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概述 


Java 内 建 的 散 列 码 [hash code] 概 念 被 限制 为 32 位 ， 并 且 没 有 分 离散 列 算法 和 它们 所 
作用 的 数据 ， 因 此 很 难 用 备 选 算法 进行 替换 。 此 外 ， 使 用 Java 内 建 方法 实现 的 散 列 
码 通常 是 劣质 的 ， 部 分 是 因为 它们 最 终 都 依赖 于 JDK 类 中 已 有 的 劣质 散 列 码 。 


Object.hashCode 往 往 很 快 ， 但 是 在 预防 碰撞 上 却 很 弱 ， 也 没有 对 分 散 性 的 预期 。 
这 使 得 它们 很 适合 在 散 列 表 中 运用 ， 因 为 额外 碰撞 只 会 带 来 轻微 的 性 能 损失 ， 同 时 
差劲 的 分 散 性 也 可 以 容易 地 通过 再 散 列 来 纠正 (Java 中 所 有 合理 的 散 列表 都 用 了 再 
散 列 方法 ) 。 然 而 ， 在 简单 散 列 表 以 外 的 散 列 运用 中 ，Object.hashCode 几 乎 总 是 
达 不 到 要 求 因此 ， 有 了 com.google.common.hash 包 。 





散 列 包 的 组 成 


在 这 个 包 的 Java doc 中 ， 我 们 可 以 看 到 很 多 不 同 的 类 ， 但 是 文档 中 没有 明显 地 表明 
它们 是 怎样 一 起 配合 工作 的 。 在 介绍 散 列 包 中 的 类 之 前 ， 让 我 们 先 来 看 下 面 这 段 代 
码 范 例 : 


HashFunction hf = Hashing.md5(); 
HashCode hc = hf.newHasher() 
. putLong(id) 
.putString(name, Charsets.UTF_8) 
.putObject(person, personFunnel) 
.hash(); 


HashFunction 


HashFunction 是 一 个 单纯 的 〈《 引 用 透明 的 ) 、 无 状态 的 方法 ， 它 把 任意 的 数据 块 映 
射 到 国定 数目 的 位 指 ， 并 且 保 证 相同 的 输入 一 定 产生 相同 的 输出 ， 不 同 的 输入 尽 可 
能 产生 不 同 的 输出 。 


Hasher 


HashFunction 的 实例 可 以 提供 有 状态 的 Hasher，Hasher 提 供 了 流畅 的 语法 把 数据 
添加 到 散 列 运算 ， 然后 获取 散 列 值 。 Hasher 可 以 接受 所 有 原生 类 型 、 字 节 数 组 、 字 
节 数 组 的 片段 、 字 符 序 列 、 特 定 字 符 集 的 字符 序列 等 等 ， 或 者 任何 给 定 了 Funnel 实 
现 的 对 象 。 


Hasher 实 现 了 PrimitiveSink 接 已， 这 个 接口 为 接受 原生 类 型 流 的 对 象 定义 了 fluent 
风格 的 API 


Funnel 


Funnel 描 述 了 如 何 把 一 个 具体 的 对 象 类 型 分 解 为 原生 字段 什 ， 从 而 写 入 
PrimitiveSink。 比 如 ， 如 果 我 们 有 这 样 一 个 类 : 


class Person { 
final int id; 
final String firstName; 
final String lastName; 
final int birthYear; 


它 对 应 的 Funnel 实 现 可 能 是 : 


Funnel<Person> personFunnel = new Funnel<Person>() { 
@Override 
public void funnel(Person person, PrimitiveSink into) { 
into 

.putInt(person.id) 
.putString(person.firstName, Charsets.UTF_8) 
.putString(person.lastName, Charsets.UTF_8) 
.putInt(birthYear ); 


注 : putString(“abc”, Charsets.UTF_8).putString(“def’, Charsets.UTF_8)% 44 MF] 
F putString(“ab”, Charsets.UTF_8).putString(“cdef’, Charsets.UTF 8)， 因 为 它们 
提供 了 相同 的 字 节 序列 。 这 可 能 带 来 预料 之 外 的 散 列 冲突 。 增 加 茶 种 形式 的 分 隔 符 
有 助 于 消除 散 列 冲突 。 


HashCode 


一 旦 Hasher 被 赋予 了 所 有 输入 ， 就 可 以 通过 hash() 方 法 获取 HashCode 实 例 (多 次 
调用 hash() 方 法 的 结果 是 不 确定 的 ) 。HashCode 可 以 通过 
asint()、asLong()、asBytes() 方 法 来 做 相等 性 检测 ， 此 外 ，writeBytesTo(array, 
offset, maxLength) 把 散 列 值 的 前 maxLength 字 节 写 入 字 节 数组 。 


布 鲁 姆 过 滤器 [BloomFilter] 


布 鲁 姆 过 滤器 是 哈 布 运算 的 一 项 优雅 运用 ， 它 可 以 简 单 地 基于 Object hashCode() 实 
现 。 简 而 言 之 ， 布 鲁 姆 过 滤器 是 一 种 概率 数据 结构 ， 它 允许 你 检测 某 个 对 象 是 一 定 
不 在 过 滤器 中 ， 还 是 可 能 已 经 添加 到 过 滤器 了 。 布 鲁 姆 过 滤器 的 维基 页 面 对 此 作 了 


全 面 的 介绍 ， 同 时 我 们 推荐 github 中 的 一 个 教程 。 


Guava 散 列 包 有 一 个 内 建 的 布 鲁 姆 过 滤器 实现 ， 你 只 要 提供 Funnel 就 可 以 使 用 它 
你 可 以 使 用 create(Funnel funnel, int expectedlnsertions, double 
falsePositiveProbability) 方 法 获取 BloomFilter<T>， 缺 省 误 检 浴 
[falsePositiveProbability] 为 3%。BloomFilter<T> 提 供 了 boolean mightContain(T) 和 
void put(T)， 它 们 的 含义 都 不 言 自明 了 。 


BloomFilter<Person> friends = BloomFilter.create(personFunnel, 5 
00, 0.01); 
for(Person friend : friendsList) { 

friends.put(friend); 


} 


// 很 久 以 后 
if (friends.mightContain(dude)) { 
/V/dude 不 是 朋友 还 运行 到 这 里 的 概率 为 1% 
// 在 这 儿 ， 我 们 可 以 在 做 进一步 精确 检查 的 同时 触发 一 些 异 步 加 载 


Hashing & 
Hashing 类 提供 了 若干 散 列 函数 ， 以 及 运算 HashCode 对 象 的 工具 方法 。 
已 提供 的 散 列 函数 


md5() murmur3_128() murmur3_32() sha1() 


sha256() sha512() goodFastHash(int bits) 


HashCode % # 
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方法 Hai 


以 有 序 方 
式 联 接 散 
列 码 ， 如 
果 两 个 散 
列 集合 用 
该 方法 联 
HashCode combineOrdered( Iterable&lt;HashCodeéggt ; ) 接 出 的 散 
列 码 相 
同 ， 那 么 
BI RS 
的 元 素 可 
能 是 顺序 
相等 的 


以 无 序 方 
式 联接 散 
列 hl, ， 如 
果 两 个 散 
列 集合 用 
该 方法 联 
接 出 的 散 
列 码 相 

同 ， 那 么 
散 列 集合 
的 元 素 可 
能 在 某 种 
排序 下 是 
相等 的 


为 给 定 

的 ” 桶 "大 
小 返回 一 
Kops Ar 
值 。 

当 ” 桶 ” 增 
长 时 ， 该 
方法 保证 
最 小 程度 
的 一 致 性 
哈 希 值 变 
化 。 详 见 
一 致 性 哈 
Ao 


HashCode combineUnordered( Iterable&lt;HashCodeggt; ) 


int consistentHash( HashCode, int buckets) 
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11- 事 件 总 线 


原文 链接 译文 连接 译 者 : 沈 义 扬 


传统 上 ，Java 的 进程 内 事件 分 发 都 是 通过 发 布 者 和 订阅 者 之 间 的 显 式 注册 实现 的 。 
设计 EventBus 就 是 为 了 取代 这 种 显示 注册 方式 ， 使 组 件 问 . on : 更 好 的 解 耦 。 
EventBus 不 是 通用 型 的 发 布 -订阅 实现 ， 不 适用 于 进程 间 通 信 


范例 


// Class is typically registered by the container. 
class EventBusChangeRecorder { 
@Subscribe public void recordCustomerChange(ChangeEvent e) { 
recordChange(e.getChange() ); 
} 


// somewhere during initialization 
eventBus.register(new EventBusChangeRecorder()); 
// much later 
public void changeCustomer() { 
ChangeEvent event = getChangeEvent(); 
eventBus.post(event); 


一 分 钟 指南 
把 已 有 的 进程 内 事件 分 发 系统 迁移 到 EventBus 非 常 简单 。 


事件 监听 者 [Listeners] 


监听 特定 事件 (如 ，CustomerChangeEvent) 


o 传统 实现 : 定义 相应 的 事件 监听 者 类 ， 如 CustomerChangeEventListener : 
e EventBus 实 现 : 以 CustomerChangeEvent 为 唯一 参数 创建 方法 ， 并 
用 Subscribe 注 解 标记 。 


把 事件 监听 者 注册 到 事件 生产 者 : 


。 传统 实现 : 调用 事件 生产 者 的 registerCustomerChangeEventListener 方 法 ; 这 
些 方法 很 少 定义 在 公共 接口 中 ， 因 此 开发 者 必须 知道 所 有 事件 生产 者 的 类 型 ， 
才能 正确 地 注册 监听 者 ; 

e EventBus 实 现 : 在 EventBus 实 例 上 调用 EventBus.register(Object) 方 法 ; 请 保 
证 事件 生产 者 和 监听 者 共享 相同 的 EventBus 实 例 。 


按 事件 超 类 监听 (如 ，EventObject 甚 至 Object ) 
o 传统 实现 : 很 困难 ， 需 要 开发 者 自己 去 实现 匹配 逻辑 ; 
e EventBus 实 现 : EventBus 自 动 把 事件 分 发 给 事件 超 类 的 监听 者 ， 并 且 允 许 监 
听 者 声明 监听 接口 类 型 和 泛 型 的 通配符 类 型 (wildcard ， 如 ? super XXX) ° 
仿 测 没有 监听 者 的 事件 : 


o 传统 实现 : 在 每 个 事件 分 发 方法 中 添加 逻辑 代码 (也 可 能 适用 AOP) ; 
e EventBus 实 现 : 监听 DeadEvent ; EventBus 会 把 所 有 发 布 后 没有 监听 者 处 理 
的 事件 包装 为 DeadEvent (对 调试 很 便利 ) 。 


事件 生产 者 [Producers] 


管理 和 追踪 监听 者 : 
o 传统 实现 : 用 列表 管理 监听 者 ， 还 要 考虑 线程 同步 ; 或 者 使 用 工具 类 ， 如 
EventListenerList ; 
e EventBus È IL : EventBus 内 部 已 经 实现 了 监听 者 管理 。 
向 监听 者 分 发 事件 : 
o 传统 实现 : 开发 者 自己 写 代 码 ， 和 包括 事 件 类 型 匹配 、 弄 常 处 理 、 异 步 分 发 ; 


e EventBus 实 现 : 把 事件 传递 给 EventBus.post(Object) 方 法 。 蜡 步 分 发 可 以 直 
接 用 EventBus 的 子 类 AsyncEventBus。 


REK 
事件 总 线 系统 使 用 以 下 术语 描述 事件 分 发 : 


事件 可 以 向 事件 总 线 发 布 的 对 象 
订阅 ”向 事件 总 线 注册 监听 者 以 接受 事件 的 行为 


1X p 
用 提供 一 个 处 理 方法 ， 希 望 接受 和 处 理事 件 的 对 象 


处 理 监听 者 提供 的 公共 方法 ， 事 件 总 线 使 用 该 方法 向 监听 者 发 送 事件 ; 该 
方法 方法 应 该 用 Subscribe 注 解 


发 市 。 通过 事件 总 线 向 所 有 匹配 的 监听 者 提供 事件 


D Za 


常见 问题 解答 [FAQ] 


为 什么 一 定 要 创建 ventBus** 实 例 ， 而 不 是 使 用 单 例 模式 ? 


EventBus 不 想 给 定 开发 者 怎么 使 用 ; 你 可 以 在 应 用 程序 中 按照 不 同 的 组 件 、 上 下 文 
或 业务 主题 分 别 使 用 不 同 的 事件 总 线 。 这 样 的 话 ， 在 测试 过 程 中 开启 和 关闭 茶 个 部 
分 的 事件 总 线 ， 也 会 变 得 更 简单 ， 影 响 范围 更 小 。 


当然 ， 如 果 你 想 在 进程 范围 内 使 用 唯一 的 事件 总 线 ， 你 也 可 以 自己 这 么 做 。 比 如 在 
容器 中 声明 EventBus 为 全 局 单 例 ， 或 者 用 一 个 静态 字段 存放 EventBus， 如 果 你 喜 
欢 的 话 。 


简 而 言 之 ，EventBus 不 是 单 例 模式 ， 是 因为 我 们 不 想 为 你 做 这 个 决定 。 你 喜欢 怎么 
用 就 怎么 用 吧 。 


可 以 从 事件 总 线 中 注销 监听 者 吗 ? 
当然 可 以 ， 使 用 EventBus.unregister(Object) 方 法 ， 但 我 们 发 现 这 种 需求 很 少 : 


e 大 多 数 监 听 者 都 是 在 局 动 或 者 模块 懒 加 载 时 注册 的 ， 并 且 在 应 用 程序 的 整个 生 
命 周 期 都 存在 ; 
e TAR LAL PRE RAR A 而 不 是 注册 /注销 监听 者 ; 
如 在 请 求 作 用 域 [request-scoped] 的 对 象 间 分 发 消息 ， 就 可 以 同样 适用 请 人 
P ak 
o 4X 建 事件 总 线 的 成 本 很 低 ， 有 时 候 可 以 通过 销毁 建 事 件 总 线 来 更 改 
ae 


为 什么 使 用 注解 标记 处 理 方 法 ， 而 不 是 要 求 监 听 者 实现 接口 ? 


我 们 觉得 注解 和 实现 接口 一 样 传达 了 明确 的 语义 ， 其 至 可 能 更 好 。 ， 使 用 注解 
也 允许 你 把 处 理 方 法 放 到 任何 地 方 ， 和 使 用 业务 意图 清晰 的 方法 命名 。 


传统 的 Java 实 现 中 ， 监 听 者 使 用 方法 很 少 的 接口 一 一 通常 只 有 一 个 方法 。 这 样 做 有 
一 些 缺 点 : 


o 监听 者 类 对 给 定 事件 类 型 ， 只 能 有 单一 处 理 逻 辑 ; 

eo 监听 者 接口 方法 可 能 冲突 ; 

© 方法 命名 只 和 事件 相关 (handleChangeEvent) ， 不 能 表达 意图 
(recordChangelnJournal) ; 

o 事件 通常 有 自己 的 接口 ， 而 没有 按 类 型 定义 的 公共 父 接口 (如 所 有 的 Ul 事件 接 


口 ) o 


接口 实现 监听 者 的 方式 很 难 做 到 简洁 ， 这 其 至 引出 了 一 个 模式 ， 尤 其 是 在 Swing 应 
用 中 ， 那 就 是 用 匿名 类 实现 事件 监听 者 的 接口 。 比 较 以 下 两 种 实现 : 


class ChangeRecorder { 
void setCustomer(Customer cust) { 
cust.addChangeListener(new ChangeListener() { 
public void customerChanged(ChangeEvent e) { 
recordChange(e.getChange()); 
} 


}; 


// 这 个 监听 者 类 通常 由 容器 注册 给 事件 总 线 
class EventBusChangeRecorder { 
@Subscribe public void recordCustomerChange(ChangeEvent e) { 
recordChange(e.getChange()); 


} 


第 二 种 实现 的 业务 意图 明显 更 加 清晰 : 没有 多 余 的 代码 ， 并 且 处 理 方法 的 名 字 是 清 
晰 和 有 意义 的 。 


通用 的 监听 者 接口 *Handler<T>** 怎 么 样 ? 


有 些 人 已 经 建议 过 用 泛 型 定义 一 个 通用 的 监听 者 接口 Handler<T>。 这 有 点 牵扯 到 
Java 类 型 擦 除 的 问题 ， 假 设 我 们 有 如 下 这 个 接口 : 


interface Handler<T> { 
void handleEvent(T event); 


} 


为 类 型 探 除 ，Java 禁 止 一 个 类 使 用 不 同 的 类 型 参数 多 次 实现 同一 个 泛 型 接口 ( 即 
不 可 能 出 现 MultiHandler implements Handler<Type1>, Handler<Type2>) 。 这 比 
起 传统 的 Java 事 件 机 制 也 是 巨大 的 退步 ， 至 少 传统 的 Java Swing 监听 者 接口 使 用 了 
不 同 的 方法 把 不 同 的 事件 区 分 开 。 


EventBus* 不 是 破坏 了 静态 类 型 ， 排 不 了 自动 重 构 支持 吗 ? 了 ** 


有 些 人 被 EventBus 的 register(Object) 和 post(Object) 方 法 直接 使 用 Object 做 参数 吓 
坏 了 。 


这 里 使 用 Object 参数 有 一 个 很 好 的 理由 : EventBus 对 事件 监听 者 类 型 和 事件 本 身 的 
类 型 都 不 作 任何 限制 。 


另 一 方面 ， 处 理 方法 必须 要 明确 地 声明 参数 类 型 期 望 的 事件 类 型 (或 事件 的 父 
类 型 ) 。 因 此 ， 搜 索 一 个 事件 的 类 型 引用 ， 可 以 马上 找到 针对 该 事件 的 处 理 方法 ， 
对 事件 类 型 的 重 命名 也 会 在 IDE 中 自动 更 新 所 有 的 处 理 方法 。 


在 EventBus 的 架构 下 ， 你 可 以 任意 重 命名 @Subscribe 注 解 的 处 理 方法 ， 并 且 这 类 

重 命名 不 会 被 传播 ( 即 不 会 引起 其 他 类 的 修改 ) ， 因 为 对 EventBus 来 说 ， 处理 方法 
的 名 字 是 无 关 紧 要 的 。 如 果 测 试 代码 中 直接 调用 了 处 理 方法 ， 那 么 当然 ， 重 命名 处 
理 方 法 会 引起 测试 代码 的 变动 ， 但 使 用 EventBus 触 发 处 理 方法 的 代码 就 不 会 发 生变 
更 。 我 们 认为 这 是 EventBus 的 特性 ， 而 不 是 漏洞 : 能 够 任意 重 命名 处 理 方 法 ， 可 以 
让 你 的 处 理 方法 命名 更 清晰 。 


如 果 我 注册 了 一 个 没有 任何 处 理 方法 的 监听 者 ， 会 发 生 什 么 ? 
什么 也 不 会 发 生 。 





EventBus 间 在 与 容器 和 模块 系统 整合 ，Guice 就 是 个 典型 的 例子 。 在 这 种 情况 下 > 
可 以 方便 地 让 容器 器 /工厂 /运行 环境 传递 任意 创 建 好 的 对 象 给 EventBus 的 
register(Object) 方 法 。 


这 样 ， 任 何 容器 /工厂 /运行 环境 创建 的 对 象 都 可 以 简便 地 通过 暴露 处 理 方 法 挂 载 到 
系统 的 事件 模块 。 


编译 时 能 检测 到 准 EventBus* 的 哪些 问题 ? 


Java 类 型 系统 可 以 明白 地 检测 到 的 任何 问题 。 比 如 ， 为 一 个 不 存在 的 事件 类 型 定 
处 理 方法 。 


运行 时 往 *EventBus* 注 册 监 听 者 ， 可 以 立即 检测 到 哪些 问题 ? 


一 旦 调用 了 register(Object) 方法 ，EventBus 就 会 检查 监听 者 中 的 处 理 方法 是 否 结 
构 正 确 的 [well-formedness]。 有 具体 来 说 ， 就 是 每 个 用 @Subscribe 注 解 的 方法 都 只 能 
有 一 个 参数 。 


违反 这 条 规则 将 引起 lllegalArgumentException (这 条 规则 检测 也 可 以 用 APT 在 编译 
时 完成 ， 不 过 我 们 还 在 研究 中 ) 。 


哪些 问题 只 能 在 之 后 事件 传播 的 运行 时 才 会 被 检测 到 ? 


如 果 组 件 传播 了 一 个 事件 ， 但 找 不 到 相应 的 处 理 方法 ，EventBus 可 能 会 指出 一 个 错 
误 (通常 是 指出 @Subscribe 注 解 的 缺失 ， 或 没有 加 载 监听 者 组 件 ) 。 


请 注意 这 个 指示 并 不 一 定 表 示 应 用 有 问题 。 一 个 应 用 中 可 能 有 好 多 场景 会 故意 忽略 
某 个 事件 ， 尤 其 当 事 件 来 源 于 不 可 控 代码 时 


你 可 以 注册 一 个 处 理 方法 专门 处 理 DeadEvent 类 型 的 事件 。 每 当 EventBus 收 到 没有 
对 应 处 理 方法 的 事件 ， 它 都 会 将 其 转化 为 DeadEvent， 并 且 传 递 给 你 注册 的 
DeadEvent 处 理 方 法 你 可 以 选择 记录 或 修复 该 事件 。 


怎么 测试 监听 者 和 它们 的 处 理 方法 ? 


因为 监听 者 的 处 理 方法 都 是 普通 方法 ， 你 可 以 简便 地 在 测试 代码 中 模拟 EventBus 调 
用 这 些 方法 。 


为 什么 我 不 能 在 *EventBus 上 使 用 < 泛 型 魔法 >?** 

EventBus 间 在 很 好 地 处 理 一 大 类 用 例 。 我 们 更 喜欢 针对 大 多 数 用 例 直 击 要 害 ， 而 不 
是 在 所 有 用 例 上 都 保持 体面 。 

此 外 ， 泛 型 也 让 EventBus 的 可 扩展 性 让 它 有 益 、 高 效 地 扩展 ， 同 时 我 们 对 
EventBus 的 增补 不 会 和 你 们 的 扩展 相 冲 突 成 为 一 个 非常 棘手 的 问题 。 

如 果 你 引 的 很 想 用 泛 型 ，EventBus 目 前 还 不 能 提供 ， 你 可 以 提交 一 个 问题 并 且 设 计 
自己 的 替代 方案 。 











12- 数 学 运算 
原文 链接 译文 链接 译 者 : 沈 义 扬 
范例 


int logFloor = LongMath.log2(n, FLOOR); 

int mustNotOverflow = IntMath.checkedMultiply(x, y); 

long quotient = LongMath.divide(knownMultipleOfThree, 3, Roundin 
gMode.UNNECESSARY); // fail fast on non-multiple of 3 

BigInteger nearestInteger = DoubleMath.roundToBigInteger(d, Roun 
dingMode.HALF_EVEN); 

BigInteger sideLength = BigIntegerMath.sqrt(area, CEILING); 


为 什么 使 用 Guava Math 


e Guava Math 针 对 各 种 不 常见 的 溢出 情况 都 有 充分 的 测试 ; 对 溢出 语义 ，Guava 
文档 也 有 相应 的 说 明 ; 如 果 运 算 的 溢出 检查 不 能 通过 ， 将 导致 快速 失败 ; 

e Guava Math 的 性 能 经 过 了 精心 的 设计 和 调 优 ; 虽然 性 能 不 可 避免 地 依据 具体 
硬件 细节 而 有 所 差异 ， 但 Guava Math 的 速度 通常 可 以 与 Apache Commons 的 
MathUtils 相 比 ， 在 某 些 场景 下 甚至 还 有 显著 提升 ; 

e Guava Math 在 设计 上 考虑 了 可 读 性 和 正确 的 编程 习惯 ; IntMath.log2(x, 
CEILING) 所 表达 的 含义 ， 即 使 在 快速 阅读 时 也 是 清晰 明确 的 。 而 32- 
Integer.numberOfLeadingZeros(x 一 1) 对 于 阅读 者 来 说 则 不 够 清晰 。 


注意 : Guava Math 和 GWT 格 外 不 兼容 ， 这 是 因为 Java 和 Java Script 语言 的 运算 洪 
出 逻辑 不 一 样 。 
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Guava Math 主 要 处 理 三 种 整数 类 型 : int、long 和 Biglnteger。 这 
具 类 分 别 叫做 IntMath、LongMath 和 BiglntegerMath 。 


有 溢出 检查 的 运算 


Guava Math 提 供 了 若干 有 溢出 检查 的 运算 方法 : 结果 溢出 时 ， 这 些 方法 将 快速 失 
败 而 不 是 忽略 溢出 


IntMath.checkedAdd LongMath. checkedAdd 


IntMath.checkedSubtract LongMath.checkedSubtract 
IntMath.checkedMultiply LongMath.checkedMultiply 
IntMath.checkedPow LongMath.checkedPow 


IntMath.checkedAdd(Integer .MAX_VALUE, Integer.MAX_VALUE); // thr 
ows ArithmeticException 


x wp ve os 
实数 运算 


IntMath、LongMath 和 BiglntegerMath 提 供 了 很 多 实数 运算 的 方法 ， 并 把 最 终 运 算 
结果 会 入 成 整数 。 这 些 方法 接受 一 个 java.math.RoundingMode 枚 举 值 作为 舍 入 的 模 
A: 


DOWN: 向 零 方 向 舍 入 〈 去 尾 法 ) 

UP : 远离 零 方向 舍 入 

FLOOR : 向 负 无 限 大 方向 舍 入 

CEILING : 向 正 无 限 大 方向 舍 入 

UNNECESSARY : 不 需要 含 入 ， 如 果 用 此 模式 进行 舍 入 ， 应 直接 抛 出 
ArithmeticException 

e HALF UP : 向 最 近 的 整数 会 入 ， 其 中 x.5 远 离 堆 方向 舍 入 

e HALF DOWN : 向 最 近 的 整数 含 入 ， 其 中 X.5 向 零 方向 舍 入 

e HALF_EVEN: 向 最 近 的 整数 舍 入 ， 其 中 X.5 向 相 邻 的 偶数 舍 入 


这 些 方法 旨 在 提高 代码 的 可 读 性 ， 例 如 ，divide(x, 3, CEILING) 即使 在 快速 阅读 时 
也 是 清晰 。 此 外 ， 这 些 方法 内 部 采用 构建 整数 近似 值 再 计算 的 实现 ， 除 了 在 构建 
sqrt (平方 根 ) 运算 的 初始 近似 值 时 有 浮 点 运算 ， 其 他 方法 的 运算 全 过 程 都 是 整数 
或 位 运算 ， 因 此 性 能 上 更 好 。 


运 
算 IntMath LongMath 


A 
A divide(int, int, RoundingMode) divide(long, long, Roundin 
í 


a log2(int, RoundingMode) log2(long, RoundingMode) 


的 log10(int, RoundingMode) log10(long, RoundingMode) 


I sqrt(int, RoundingMode) sqrt(long, RoundingMode) 


// returns 31622776601683793319988935444327185337195551393252 
BigIntegerMath.sqrt(BigInteger.TEN.pow(99), RoundingMode.HALF_EV 
EN); 


附加 功能 


Guava 还 另外 提供 了 一 些 有 用 的 运算 函数 


P IntMath LongMath BiglntegerMath* 


公 qedl(ne Time) gcd(long, long) BigInteger .gcd(E 


mod(int, int) mod(long, long) BigInteger .mod(E 


pow(int, int) pow(long, int) BigInteger .pow(i 


isPowerOfTwo(int ) isPowerOfTwo(long) isPowerOfTwo(Bic 


a RN Ww Hs 


factorial(int) factorial(int) factorial(int) 


binomial(int, int) binomial(int, int) binomial(int, ir 


A 
BL 


*Biglnteger 的 最 大 公约 数 和 取 模 运算 由 JDK 提 供 
* 阶 乘 和 二 项 式 系数 的 运算 结果 如 果 溢 出 ， 则 返回 MAX_VALUE 
浮 点 数 运算 


JDK 比 较 彻 底 地 涵盖 了 浮 点 数 运 算 ， 但 Guava 在 DoubleMath 类 中 也 提供 了 一 些 有 用 
的 方法 。 


12- 数 学 
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整数 
全 XI i z z ANE 、 
roundToInt(double, RoundingMode) ue i 数 
ma 


4 Along ; 对 无 限 小 
数 、 溢 出 抛 出 异常 

4 AA Biginteger ; 对 无 
限 小 数 抛 出 异常 


2 的 浮 点 对 数 ， 并 且 舍 入 
log2(double, RoundingMode) 为 int ， 比 JDK 的 
Math.log(double) 更 快 


roundToLong(double, RoundingMode) 


roundToBigInteger (double, RoundingMode ) 


1161 


13- 反 射 


译 者 : J RAIRA) 


由 于 类 型 擦 除 ， 你 不 能 够 在 运行 时 传递 泛 型 类 对 象 一 你 可 能 想 强制 转换 它们 ， 并 
假装 这 些 对 象 是 有 泛 型 的 ， 但 实际 上 它们 没有 。 


举 个 例子 : 


ArrayList<String> stringList = Lists.newArrayList(); 
ArrayList<Integer> intList = Lists.newArrayList(); 
System.out.printin(stringList.getClass().isAssignableFrom(intLis 
t.getClass())); 

returns true, even though ArrayList<String> is not assignable fr 
om ArrayList<Integer> 


Guava 提 供 了 TypeToken, 它 使 用 了 基于 反射 的 技巧 甚至 让 你 在 运行 时 都 能 够 巧妙 的 
操作 和 查询 泛 型 类 型 。 想 象 一 下 TypeToken 是 创建 ， 操 作 ， 查 询 泛 型 类 型 (以 及 ， 
隐 含 的 类 ) 对 象 的 方法 。 


Guice 用 户 特别 注意 : TypeToken 与 类 Guice 的 TypeLiteral 很 相似 ， 但 是 有 一 个 点 特 
别 不 同 : 它 能 够 支持 非 具体 化 的 类 型 ， 例 如 T，List<T>， 甚 至 是 List<? extends 
Number> ; TypeLiteral 则 不 能 支持 。TypeToken 也 能 支持 序列 化 并 且 提 供 了 很 多 额 
外 的 工具 方法 。 


背景 : 类 型 擦 除 与 反射 


Java 不 能 在 运行 时 保留 对 象 的 泛 型 类 型 信息 。 如 果 你 在 运行 时 有 一 个 
ArrayList<String> 对 象 ， 你 不 能 够 判定 这 个 对 象 是 有 泛 型 类 型 ArrayList<String> 的 
一 并 且 通 过 不 安全 的 原始 类 型 ， 你 可 以 将 这 个 对 象 强制 转换 成 
ArrayList<Object> ° 


但 是 ， 反 射 允 许 你 去 检测 方法 和 类 的 泛 型 类 型 。 如 果 你 实现 了 一 个 返回 List 的 方 
法 ， 并 且 你 用 反射 获得 了 这 个 方法 的 返回 类 型 ， 你 会 获得 代表 List<String> 的 
ParameterizedType ° 


TypeToken 类 使 用 这 种 变通 的 方法 以 最 小 的 语法 开销 去 支持 泛 型 类 型 的 操作 。 


介绍 


获取 一 个 基本 的 、 原 始 类 的 TypeToken 非 常 简单 : 


TypeToken<String> stringTok = TypeToken.of(String.class); 
TypeToken<Integer> intTok = TypeToken.of(Integer.class); 


为 获得 一 个 含有 泛 型 的 类 型 的 TypeToken 一 一 当 你 知道 在 编译 时 的 泛 型 参数 类 型 
一 一 你 使 用 一 个 空 的 匿名 内 部 类 : 


TypeToken<List<String>> stringListTok = new TypeToken<List<Strin 


g>>() {}; 


RAR MK EAS an 通配符 类 型 : 


TypeToken<Map<?, ?>> wildMapTok = new TypeToken<Map<?, ?>>() {}; 


TypeToken 提 供 了 一 种 方法 来 动态 的 解决 泛 型 类 型 参数 ， 如 下 所 示 : 


static <K, V> TypeToken<Map<K，V>> mapToken(TypeToken<K> keyToke 
n, TypeToken<V> valueToken) { 
return new TypeToken<Map<K, V>>() {} 
.where(new TypeParameter<K>() {}, keyToken) 
.where(new TypeParameter<V>() {}, valueToken); 


} 


TypeToken<Map<String, BigInteger>> mapToken = mapToken( 
TypeToken.of(String.class), 
TypeToken.of (BigInteger.class) 

); 

TypeToken<Map<Integer, Queue<String>>> complexToken = mapToken( 
TypeToken.of(Integer.class), 
new TypeToken<Queue<String>>() {} 


); 


注意 如 果 mapToken 只 是 返回 了 new TypeToken>()， 它 实际 上 不 能 把 具体 化 的 类 型 
分 配 到 K 和 V 上 面 ， 举 个 例子 


class Util { 
static <K, V> TypeToken<Map<kK, V>> incorrectMapToken() { 
return new TypeToken<Map<K, V>>() {}; 


} 
} 
System.out.println(Util.<String, BigInteger>incorrectMapToken()) 


了 
// just prints out "java.util.Map<K, V>" 


或 者 ， 你 可 以 通过 一 个 子 类 (通常 是 匿名 ) 来 捕获 一 个 泛 型 类 型 并 且 这 个 子 类 也 可 
以 用 来 替换 知道 参数 类 型 的 上 下 文 类 。 


abstract class IKnowMyType<T> { 
TypeToken<T> type = new TypeToken<T>(getClass()) {}; 


} 


new IKnowMyType<String>() {}.type; // returns a correct TypeToke 
n<String> 


使 用 这 种 技术 ， 你 可 以 ， 例 如 ， 获 得 知道 他 们 的 元 素 类 型 的 类 。 


查询 
TypeToken 支 持 很 多 种 类 能 支持 的 查询 ， 但 是 也 会 把 通用 的 查询 约束 考虑 在 内 。 
支持 的 查询 操作 包括 : 


方法 描述 
getType() 获得 包装 的 java.lang.reflect.Type. 
getRawType() 返回 大 家 熟知 的 运行 时 类 


返回 那些 有 特定 原始 类 的 子 类 型 。 举 个 例子 ， 如 果 
getSubtype(Class<?>) 这 有 一 个 lterable 并 且 参 数 是 List.class， 那 么 返回 将 

是 List ° 

产生 这 个 类 型 的 超 类 ， 这 个 超 类 是 指定 的 原始 类 

? 

型 。 举 个 例子 ， 如 果 这 是 一 个 Set 并 且 参 数 是 

lterable.class， 结 采 将 会 是 lterable。 

如 果 这 个 类 型 是 assignable from 指定 的 类 型 ， 并 且 
isAssignableFrom(type) ”考虑 泛 型 参数 ， 返 回 true 。List<? extends Number> 

是 assignable from List， 但 List 没 有 . 

返回 一 个 Set， 包 含 了 这 个 所 有 接口 ， 子 类 和 类 是 这 
getTypes() 个 类 型 的 类 。 返 回 的 Set 同 样 提供 了 classes() 和 

interfaces() 方 法 允许 你 只 浏览 超 类 和 接口 类 。 


检查 某 个 类 型 是 不 是 数组 ， 甚 至 是 <? extends 
A> ° 


getComponentType() 返回 组 件 类 型 数组 。 


isArray() 


resolveType 


resolveType 是 一 个 可 以 用 来 “替代 ”context token ( 译 者 : 不 知道 怎么 翻译 ， 只 好 去 
stackoverflow 去 问 了 ) 中 的 类 型 参数 的 一 个 强大 而 复杂 的 查询 操作 。 例 如 ， 


TypeToken<Function<Integer, String>> funToken = new TypeToken<Fu 
nction<Integer, String>>() {}; 


TypeToken<?> funResultToken = funToken.resolveType(Function.clas 
s.getTypeParameters()[1])); 
// returns a TypeToken<String> 


Type Token 44 Javad # 49 TypeVariables#* context token 中 的 类 型 变量 统一 起 来 。 这 
可 以 被 用 来 一 般 性 地 推断 出 在 一 个 类 型 相关 方法 的 返回 类 型 : 


TypeToken<Map<String, Integer>> mapToken = new TypeToken<Map<Str 
ing, Integer>>() {}; 

TypeToken<?> entrySetToken = mapToken.resolveType(Map.class.getM 
ethod("entrySet").getGenericReturnType()); 

// returns a TypeToken<Set<Map.Entry<String, Integer>>> 


Invokable 


Guava 4 Invokable z *tjava.lang.reflect.Method#*java.lang.reflect.Constructor®9 ii 
式 包装 。 它 简化 了 常见 的 反射 代码 的 使 用 。 一 些 使 用 例子 : 


方法 是 否 是 public 的 ? 
JDK: 


Modifier .isPublic(method.getModifiers()) 


Invokable: 


invokable.isPublic() 


A kx Tx package private? 


JDK: 


!(Modifier.isPrivate(method.getModifiers()) || Modifier.isPublic 
(method.getModifiers())) 


Invokable: 


invokable.isPackagePrivate() 


方法 是 否 能 够 被 子 类 重 写 


JDK: 


!(Modifier.isFinal(method.getModifiers()) 

|| Modifiers.isPrivate(method.getModifiers() ) 

|| Modifiers.isStatic(method.getModifiers() ) 

|| Modifiers.isFinal(method.getDeclaringClass().getModifiers())) 


Invokable: 


invokable.isOverridable( ) 


方法 的 第 一 个 参数 是 否 被 定义 了 注解 @Nullable ? 
JDK: 


for (Annotation annotation : method.getParameterAnnotations [QO] ) 


if (annotation instanceof Nullable) { 
return true; 


} 


return false; 


Invokable: 


invokable.getParameters().get(0).isAnnotationPresent(Nullable.cl 
ass) 


构造 函数 和 工厂 方法 如 何 共 享 同样 的 代码 ? 


你 是 否 
方法 中 


Invokable 提 供 了 一 个 抽象 的 概念 。 下 面 的 代码 适合 任何 一 种 方法 或 构造 函数 


很 想 重 复 自 己 ， 因 为 你 的 反射 代码 需要 以 相同 的 方式 工作 在 构造 函数 和 工厂 
4 


invokable.isPublic(); 
invokable.getParameters(); 
invokable.invoke(object, args); 


List 的 List.getkint) 返 回 类 型 是 什么 ? Invokable 提 供 了 与 众 不 同 的 类 型 解决 方案 : 


Invokable<List<String>, ?> invokable = new TypeToken<List<String 
>>() {}.method(getMethod) ; 
invokable.getReturnType(); // String.class 


Dynamic Proxies 


newProxy() 


实用 方法 Reflection.newProxy(Class, InvocationHandlem) 是 一 种 更 安全 ， 更 方便 的 
API， 它 只 有 一 个 单一 的 接口 类 型 需要 被 代理 来 创建 Java 动 态 代理 时 
JDK: 
Foo foo = (Foo) Proxy.newProxyInstance( 
Foo.class.getClassLoader(), 


new Class<?>[] {Foo.class}, 
invocationHandler ); 


Guava: 


Foo foo = Reflection.newProxy(Foo.class, invocationHandler ); 


AbstractlInvocationHandler 


有 时 候 你 可 能 想 动 态 代理 能 够 更 直观 的 支持 equals()，hashCode() 和 toString()， 那 
就 是 : 
1. 一 个 代理 实例 equal 另 外 一 个 代理 实例 ， 只 要 他 们 有 同样 的 接口 类 型 和 equal 的 
invocation handlers ° 
2. 一 个 代理 实例 的 toString() 会 被 代理 到 invocation handler49toString() > RŽ # 
H => 
AA KL e 


AbstractInvocationHandler % 5, J A LZ $ © 


除 此 之 外 ，AbstractlnvocationHandler 确 保 传递 给 handlelnvocation(Object， 
Method, Object[]) 的 参数 数组 永远 不 会 室 ， 从 而 减少 了 空 指 针 异 常 的 机 会 。 


ClassPath 


严格 来 讲 ， Java 没 有 平台 无 关 的 方式 来 浏览 类 和 类 资源 。 不 过 一 定 的 包 或 者 工程 
下 ， 还 是 能 够 实现 的 ， 上 比方 说 ， 去 检查 菜 个 特定 的 工程 的 惯例 或 者 某 种 一 直 遵 从 的 
约束 。 


ClassPath 是 一 种 实用 工具 ， 它 提供 尽 最 大 努力 的 类 路 径 扫 描 。 用 法 很 简单 : 


ClassPath classpath = ClassPath.from(classloader); // scans the 
class path used by classloader 

for (ClassPath.ClassInfo classInfo : classpath.getTopLevelClasse 
s("com.mycomp.mypackage")) { 


} 


在 上 面 的 例子 中 ，Classlnfo 是 被 加 载 类 的 句柄 。 它 允许 程序 员 去 检查 类 的 名 字 和 和 包 
的 名 字 ， 让 类 直到 需要 的 时 候 才 被 加 载 。 


值得 注意 的 是 ，ClassPath 是 一 个 尽力 而 为 的 工具 。 它 只 扫描 jar 文 件 中 或 者 某 个 


件 目 录 下 的 class 文 件 。 也 不 能 扫描 非 URLCIlassLoader 的 自 定 义 class loader 管 理 的 
class， 所 以 不 要 将 它 用 于 关键 任务 生产 任务 。 


Class Loading 


工具 方法 Reflection.initialize(Class...) 能 够 确保 特定 的 类 被 初始 化 一 一 执行 任何 静 
态 初 始 化 。 


使 用 这 种 方法 的 是 一 个 代码 异味 ， 因 为 静态 伤害 系 — 性 和 可 测试 性 。 在 有 
些 情况 下 ， 你 别 无 选择 ， 而 与 传统 的 框架 ， 操 作 间 一 方法 有 助 于 保持 代码 不 那 
2H o 
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1 简介 


1.1 什么 是 JFreeChart 


1.1.1 概述 

JFreeChart 是 一 款 免费 的 java 图 形 开发 类 库 。 主 要 用 来 在 application/ applets/ 
servlets/ jsp/ 上 生成 各 种 图 表 。JFreeChart 是 完全 开源 ， 并 且 严 格 遵循 GNU 的 通用 
公共 许可 证 ， 力 保 JFreeChart 用 户 对 源 代 码 的 自由 修改 与 使 用 。 


Dual Axis Chart 














Category 


ESI ES? @S3 





图 1.1 一 个 简单 的 图 表 


图 1.1 就 是 一 个 典型 的 使 用 JFreeChart 创 建 的 图 表 。 在 本 文 后 续 章 节 将 陆续 展示 更 多 
的 实例 。 


1.1.2 特征 


JFreeChart 能 产生 人 饼 图 (pie) 、 柱 状 /条 形 统计 图 (bar) 、 折 线 图 (line) 、 散 点 
图 (scatter plots) 、 时 序 图 (time series) ` +4 B (Gantt) 、 仪 表盘 图 
(meter > We ZÊ ` BAH FAF) 、 混 合 图 、symbol 图 和 风力 方向 图 等 。 


主要 特征 如 下 : 


o 定义 接口 的 任何 实现 通俗 易 懂 

易于 导出 PNG 和 JPEG 图 像 文 件 格式 〈 也 可 以 使 用 java 的 图 像 JO 类 库 生 成 类 库 
支持 的 任何 格式 ) 。 

使 用 Graphics2D 工 具 导 出 其 他 格式 : 

使 用 iText 工 具 导 出 PDF 格式 文件 

使 用 Batik 工 具 导 出 SVG 格式 文件 

图 像 工 具 栏 

AR Xa BH 

支持 注解 。 


e 产生 HTML 图 像 映 射 
e 可 以 工作 于 application/servlets/jsp/applets 等 环境 。 
e 完全 开源 、 严 格 遵 守 GNU 的 通用 公共 认证 协议 。 


JFreeChart 完 全 由 java 语 言 编写 ， 可 以 运行 在 java2 的 任何 平台 上 (JDK1.3.1 版 本 或 
者 更 高 版 本 ) 

1.1.3 下 载 主页 

JFreeChart 可 以 在 下 面 的 链接 中 找到 : 


http://www.jfree.org/jfreechart/ 这 里 我 们 可 以 找到 JFreechart 最 新 的 版 本 ， 目 前 是 
1.0.6。 包 括 图 表 实 例 、 下 载 链 接 、javadoc 文 档 、 讨 论 社区 等 。 


1.2 使 用 文档 


文档 有 两 个 有 效 的 版 本 : 


e 免费 版 本 可 以 充 JFreeChart 主 网 站 上 下 载 免费 版 本 《JFreeChart Installation 
Guide) ， 主 要 讲述 内 容 是 : JFreeChart 的 安装 过 程 和 JFreeChart 实 例 的 运 
行 。 

o 收费 版 本 需要 支付 一 定 费 用 才能 获得 《JFreeChart Developer Guide) > +% 
包括 开发 指南 章节 和 JFreeChart 类 参考 文档 。 


1.3 感谢 


JFreeChart 的 代码 和 思路 源 于 很 多 人 。 在 这 里 我 将 感谢 下 面 帮助 JFreeChart 成 长 的 
A eR LARS Fide > LAP E> At RRRMEe ZGRF: 


Richard Atkinson, David Berry, Anthony Boulestreau, Jeremy Bowman, Daniel 
Bridenbecker, Nicolas Brodu, David Browning, S@ren Caspersen, Chuanhao Chiu, 
Pascal Collet, Martin Cordova, Paolo Cova, Michael Duffy, Jonathan Gabbai, 
Serge V. Grachov, Hans-Jurgen Greiner, Joao Guilherme Del Valle, Aiman Han, 
Jon lles, Wolfgang Irler, Xun Kang, Bill Kelemen, Norbert Kiesel, Gideon Krause, 
Arnaud Lelievre, David Li, Tin Luu, Craig MacFarlane, Achilleus Mantzios, 
Thomas Meier, Aaron Metzger, Jim Moore, Jonathan Nash, Barak Naveh, David 
M. O’Donnell, Krzysztof Paz, Tomer Peretz, Andrzej Porebski, Luke Quinane, 
Viktor Rajewski, Eduardo Ramalho, Michael Rauch, Cameron Riley, Dan Rivett, 
Michel Santos, Thierry Saura, Andreas Schneider, Jean-Luc Schwab, Bryan Scott, 
Roger Studner, Irv Thomae, Eric Thomas, Rich Unger, Daniel van Enckevort, 
Laurence Vanhelsuw’e, Sylvain Vieujot, JelaiWang, MarkWatson, Alex Weber, 
Matthew Wright, Christian W. Zuckschwerdt, Hari and Sam (oldman). 


1.4 建议 


如 果 您 对 本 文档 有 任何 的 建议 或 想法 ， 请 发 送 : david.gilbert@object- 
refinery.com ° 


2 图 表 实 例 


2.1 介绍 
本 章节 显示 了 许多 使 用 JFreeChart 创 建 的 图 表 实 例 。 内 容 特 意 对 JFreeChart 产 生 的 
图 表 类 型 做 了 概述 。 运 行 实例 命令 如 下 : 


java -jar jfreechart-1.0.6-demo. jar 


如 果 您 购买 了 《JFreeChart Developer Guide》， 可 获得 该 实例 的 源 代码 。 


2.2 饼 图 (Pie Charts) 


2.2 t+ (Pie Charts) 


JFreeChart 能 够 创 使 用 符合 PieDataset 接 口 标准 的 数据 创建 饼 图 。 下 图 2.1 显 示 了 一 


个 简单 的 饼 图 。 


Pie Chart Demo 1 











图 2.1 一 个 简单 的 人 饼 图 (参见 : PieChartDemot java) 
其 中 ， 单 个 的 区 域 也 可 以 被 “取出 ”， 如 下 图 2.2 所 示 : 


Pie Chart Demo 2 


[Six (16% percent) | 


—— {One 34% percent)| 


Four(14% percen 一 一 一 a 
| 





图 2.2 一 个 带 有 取出 “区域 " 的 饼 图 〈 参 见 : PieChartDemo2.java ) 
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2.2 人 饼 图 (Pie Charts) 


我 们 也 可 以 显示 3D 效 果 的 人 饼 图 ， 如 下 图 2.3 所 示 : 
Pie Chart 3D Demo 1 








@ Java @ Visual Basic @ C/C++ © PHP @ Perl 


图 2.3 3D 效 果 图 的 图 表 (参见 : PieChart3DDemo1 java) 
3D 效 果 的 饼 图 ， 部 分 区 域 不 能 取出 。 
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2.3 直方 条 形 图 (Bar Charts) 


JFreeChart 可 以 创建 一 系列 的 直方 条 形 图 。 创 建 直 方 条 形 图 的 数据 必须 符合 
CategoryDataset 接 口 标准 。 图 2.4 显 示 了 一 个 垂直 定向 的 直方 条 形 图 。 





Bar Chart Demo 1 





he wo 


o% e 


© D © ww 已 al (A D 


Category 


图 2.4 一 个 重 直 的 直方 条 形 图 (参见 : BarChartDemo1.java) 
直方 条 形 图 可 以 用 3D 效 果 显 示 ， 如 下 图 2.5 所 示 。 





3D Bar Chart Demo 


W 9 dy 


owe on ` oat got? oo” oat oe" 


Category 


Senes1 E Series 2 ™Series3 Series4 5 Series 5 Senes6 Series? @Series8 W Series 9 





如 2.5 3D 效 果 的 直方 条 形 图 (参见 : BarChart3DDemo1.java) 


2.3 2% 4% A (Bar Charts) 


直方 条 形 图 的 另 一 种 变型 ， 瀑 布 图 表 。 如 下 图 2.6 所 示 : 
Product Cost Breakdown 


= 
E 
2 
D 
a. 
w 
o 
o 


Administration Marketing Distribution Total Expense 
Expense Category 





402.6 一 个 瀑布 图 表 (参见 : WaterfallChartDemo1 java) 
直方 条 形 图 可 以 从 时 序数 据 中 产生 。 如 下 图 2.7 所 示 : 
State Executions - USA 


Source: http Awww. amnestyusa orgy/abolishfisthyyeardo 


= 


Number of People 
8 8 & 8 8 3 8 8B 


o = 
1976 1976 1980 1982 1984 1986 1988 1990 1992 1994 1996 1998 2000 2002 2004 
Year 





图 2.7 一 个 XY 图 表 (#4 XYBarChartDemo1 java ) 
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2.4 折线 图 (Line Charts) 


2.4 折线 图 (Line Charts ) 


折线 图 可 以 使 用 直方 条 形 图 的 数据 对 象 CategoryDataset 产 生 。 如 下 图 2.8 : 


j IERE- 


Pg T magii f g 








图 2.8 一 个 折线 图 (参考 LineChartDemo1.java) 
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2.5 XY( 散 点 图 ) 


2.5 XY( 散 点 图 ) 


XYDataset 是 第 三 种 数据 类 型 ， 用 来 产生 一 系列 图 表 的 类 型 。 标 准 的 XY 区 域 有 X 和 
Y 数 轴 。 默 认 的 ， 使 用 相应 的 数据 按照 一 定 比例 画 出 X 轴 和 Y 轴 。 如 图 2.9 所 示 。 





Line Chart Demo 4 








图 2.9 折线 图 (参考 : LineChartDemo4 java ) 


散 点 图 是 每 一 个 数据 点 用 一 个 图 形 画 出 来 ， 而 不 是 使 用 线 将 点 连 起 来 。 一 个 实例 如 
下 图 2.10 所 示 : 


Scatter Plot Demo 1 











x 
@ Sample0 è Sample1 4 Sample2 © Sample 3 
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图 2.10 散 点 图 (参考 : ScatterPlotDemo1 java ) 


2.6 时 序 图 


26H A 


JFreeChart 支 持 时 间 序 列 图 表 ， 时 序 图 包括 平均 值 图 、high-low-open-close 图 和 
candlestick 图 ， 如 下 图 2.11 上 所 示 : 


Legal & General Unit Trust Prices 


= 
c 
=] 
_ 
中 
a 
v 
o 
= 
a 





图 2.11 序列 图 (参考 : TimeSeriesDemo1 java) 
我 们 可 以 在 时 序 图 上 添加 一 条 平均 值 线 一 一 如 下 图 2.12 所 示 : 





Time Series Demo 8 





五 月 .2001 七 月 ,2001 九 月 .2001 i- -月 .2001 
Date 


— EUR/GBP — 30 day moving average 


A212 带 有 平均 线 线 的 时 序 图 (参考 : TimeSeriesDemo8 java ) 
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我 们 可 以 使 用 OHLCDataset (XYDataset 的 扩展 ) 显示 high-low-open-close 数 据 图 
表 。 如 下 图 2.13 所 示 : 








OHLC Demo 2 
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E Series 1 — Series 1-MAVG 


图 2.13 high-low-open-closeA & (参考 : HighLowChartDemo2.java) ) 
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2.7 柱状 图 


2.7 柱状 图 


可 以 使 用 一 个 IntervalXYDataset (XYDataset 的 另 一 个 扩展 ) 数据 产生 柱状 图 。 如 
下 图 2.14 所 示 : 


Histogram Demo 1 





20 25 30 36 40 45 60 55 60 65 70 75 80 85 90 95 100 





图 2.14 柱状 图 (参考 : HistogramDemo1 java) 
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2.8 面积 图 


2.8 面积 图 


我 们 可 以 使 用 CategoryDataset 或 者 XYDataset 产 成 面积 图 表 。 如 下 图 2.15 所 示 : 


XY Area Chart Demo 


Domain (x) 


a Random 1 @ Random 2 


图 2.15 面积 图 (参考 : XYAreaChartDemo1 java ) 
同时 ，JFreeChart 也 支持 堆栈 式 面 积 图 表 ， 如 下 图 2.16 所 示 : 





Stacked XY Area Chart Demo 1 





12 13 
xX Value 


图 2.16 堆栈 式 面积 图 〈 参 考 : StackedXYAreaChartDemo1 java ) 
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2.8 面积 图 
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2.9 差异 图 


2.9 差异 图 


差异 图 是 显示 两 个 序列 之 间 的 不 同 。 如 下 图 2.17 所 示 。 


Difference Chart Demo 1 


上 “月 -2007 上 一 用 -2007 -2008 _})-2008 三 月 -2008 园 川 -2008 
Time 


图 2.17 差异 图 (参考 DifferenceChartDemo1 java) 


Daylight Hours - London, UK 


Data source: http/wwew.sunrisesunsetcom/ 


回 咱 -2004 六 中 -2004 从 月 -2004 |-2004 
Time 


图 2.18 差异 图 (参考 : DifferenceChartDemo2.java) 


五 月 -200 





| 一 月 -2004 
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2.9 差异 图 
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2.10 梯形 图 


2.10 梯形 图 


梯形 图 使 用 一 系列 的 “梯形 "来 显示 数据 数值 。 如 下 图 2.19 所 示 : 





XYStepRenderer Demo 1 





x 
图 2.19 梯形 图 (参考 : XYStepRendererDemo1.java) 
梯形 图 数据 使 用 XYDataset 数 据 对 象 。 





2.11 甘 特 图 


2.11 甘 特 图 


我 们 可 以 使 用 IntervalCategoryDataset 数 据 集 类 产生 甘 特 图 。 如 图 2.20 所 示 


Gantt Chart Demo 


Date 
五 月 -2001 





Write Proposal 


Obtain Approval 


Requirements Analysis 
Design Phase 

Design Signoff 

Alpha Implementation 
Design Review 

Revised Design Signoff 
Beta Implementation 
Testing 

Final Implementation 


Signoff 








E Scheduled @ Actual 


图 2.20 +44 A (参考 : GanttChartDemo1 java ) 
此 外 ， 甘 特 图 可 以 具有 子 任务 和 进度 显示 器 。 如 下 图 2.21 所 示 


Gantt Chart Demo 


Date 
儿 月 -2001 


Write Proposal 

Obtain Approval 
Requirements Analysis 
Design Phase 

Design Signoff 

Alpha Implementation 
Design Review 
Revised Design Signoff 
Beta Implementation 
Testing 

Final Implementation 


Signoff 





E Scheduled 


图 2.21 带 有 进度 显示 的 甘 特 图 
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2.11 甘 特 图 
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2.12 多 轴 图 


2.12 2 4h A 


JFreeChart 支 持 多 轴 图 表 。 如 下 图 2.22 显 示 了 一 个 价格 一 数量 的 图 表 。 





Eurodollar Futures Contract (MAR03) 





D 
h -2002 + -H-2002 





图 2.22 价格 一 数量 图 表 (参考 : PriceVolumeDemo1.java) 
CategoryPlot 和 XYPot 支 持 多 轴 特 征 。 图 2.23 显 示 了 一 个 具有 四 个 数 轴 的 图 表 。 


Multiple Axis Demo 1 
Four datasets and four range axes. 


Range Axis 2 
Primary Range Axis 
E Siy auey 


15:00 15:30 16:00 16:30 17:00 17:30 18:00 
Time of Day 


图 2.23 多 轴 图 表 (参考 : MultipleAxisDemo1 java ) 
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2.12 多 轴 图 
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2.13 复合 /和 覆盖 图 


2.13 复合 / 复 盖 图 


JFreeChart 支 持 复合 /覆盖 图 表 。 图 2.24 显 示 了 一 个 条 形 图 上 和 堆 盖 了 一 个 折线 图 。 


Freshmeat Software Projects 


By Programming Language 
As at 5 March 2003 


Unix Shell 





图 2.24 &&A (#4 : ParetoChartDemo1.java) 
也 有 可 能 使 用 同一 个 主轴 ， 组 合 几 种 图 表 。 如 下 图 2.25 © 


a 


o- N O A Q @ N O 





Type 4 Type 2 Type 3 Type 4 Type 5 Type 6 Tepe 7 


Category 


图 2.25 带 有 公共 区 域 的 图 表 (参考 : CombinedCategoryPlotDemot java ) 
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2.13 ZAR áA 


类 似 的 ，JFreeChart 可 以 复合 几 种 图 表 ， 共 用 相同 刻度 范围 的 轴 。 如 图 2.26 所 示 : 





Combined (Range) XY Plot 





E Series 1 — Series 2 


图 2.26 共用 相同 范围 轴 的 复合 图 表 (参考 : CombinedXYPlotDemo2.java) 
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2.14 开发 远景 


JFreeChart 为 免费 软件 ， 任 何人 可 以 扩展 它 ， 可 以 添加 新 的 特征 。 已 经 有 80 多 人 向 
JFreeChart 项 目 贡 献 代 码 。 不 久 开发 者 将 开发 更 多 的 图 表 来 满足 更 多 的 需求 。 我 们 
可 以 从 JFreeChart 网 站 上 获得 更 多 的 信息 和 版 本 的 更 新 : 


http://www. jfree.org/jfreechart/ 


欢迎 您 的 加 入 。 


3 下 载 和 安装 JFreeChart 1.0.6 


3.1 简介 


本 章 主 要 介绍 JFreeChart 的 下 载 、 解 包 和 编译 内 容 。 同 时 讲述 如 何 运行 JireeChart 
应 用 实例 ， 如 何 从 源 代 码 生 成 JavaDoc 的 HTML 文 件 内 容 等 。 


3.2 TR 


我 们 可 以 从 JFreeChart 主 网 站 上 获得 最 新 的 JFreeChart 版 本 : 
http://www.jfree.org/jfreechart/download 
网 页 上 提供 了 两 个 可 下 载 的 版 本 : 
文件 描述 
jfreechart-1.0.6.tar.gz Linux/Unix 版 本 
jfreechart-1.0.6.zip Windows 版 本 
这 两 个 文件 包含 相同 的 源 代码 。 主 要 不 同 在 于 下 载 的 zip 文 件 中 所 有 的 文本 文件 已 被 
重新 编码 ， 有 回 车 返回 ， 并 且 每 行 结尾 有 换行 符号 。 
JFreeChart 是 有 JCommon (目前 版 本 是 1.0.9) 基础 类 库 .JCommon 是 运行 时 的 jar 
文件 ， 在 JFreeChart 下 载 时 ， 包 含 该 jar 文 件 。 如 果 你 需要 JCommon 的 源 代码 ， 可 
以 从 下 面 链接 下 载 : 


http://www.jfree.org/jcommon/ 


3.3 解 包 


下 载 完 JFreeChart 压 缩 文 件 之 后 ， 我 们 需要 将 该 压缩 文件 解 开 。 我 们 可 以 将 文件 解 
压 到 指定 的 目录 下 面 。 


3.3.1 Linux/Unix 环 境 下 解压 
在 Linux/Unix 环 境 下 解压 文件 ， 使 用 下 面 命令 


tar xvzf jfreechart-1.0.6.tar.gz tar xvzf jfreechart-1.0.6.tar.g 
Z 


六 命令 将 JFreeChart 所 有 的 文件 包括 源 代码 ， 运 行 jar 文 件 和 doc 文 档 解压 到 
oe 1068 xr mo 


3.3.2 Windows 243% F ARE 
在 Windows 环 境 下 解压 文件 ， 使 用 下 面 命令 


jar -xvf jfreechart-1.0.6.zip 


六 命令 将 JFreeChart 所 有 的 文件 包括 源 代码 ， 运 行 jar 文 件 和 doc 文 档 解压 到 
ec. 1068 xr mo 


3.3.3 文件 目录 说 明 


解压 后 的 jfreechart-1.0.6 目 录 下 面 ， 有 许多 文件 和 文件 夹 ， 列 表 如 下 


文件 /目录 


Ant 


checkstyle 


experimental 
gjdoc 

lib 

source 

swt 


Tests 


jfreechart-1.0.6- 
demo.jar 


CHANGELOG .txt 
ChangeLog 
licence-LGPL .txt 
NEWS 
README .txt 


说 明 


该 目录 下 面包 含 了 一 个 ant 的 build.xml 脚 本 。 我 们 使 用 该 脚 
本 可 以 用 现 有 的 版 本 源 代 码 重 新 构建 JFreeChart。 


该 目录 下 面包 含 了 几 种 检查 风格 属性 文件 。 文 件 定义 了 
JFreeChart 中 的 编码 规范 。 


该 文件 夹 下 面包 含 了 一 些 不 属于 JFreeChart 标 准 API| 的 类 文 
件 。 注 意 这 些 代 码 的 AP| 可 能 会 改变 。 


该 文件 夹 下 面包 含 了 一 种 产生 JFreeChart 文 档 的 脚本 。 


该 目录 下 面包 含 了 JFreeChart 的 jar 文 件 ， 以 及 JFreeChart 
依赖 的 jar 文 件 。 


JFreeChart 源 代码 目录 。 


该 目录 下 面包 含 了 具有 实践 经 验 的 Swt 源 代码 。 注 意 该 代码 
API 有 可 能 发 生 改 变 。 


JFreeChart 单 元 测试 的 源 代 码 文 件 。 
一 个 具有 实例 演示 的 可 运行 的 jar 文 件 。 


老 的 JFreeChart 变 更 的 日 志 记 录 。 
JFreeChart 变 更 的 详细 日 志 记 录 。 
JFreeChart 公 共 认 证 (GNU LGPL) 
JFreeChart 项 目 新 闻 

重要 信息 一 一 定 要 读 | 


我 们 应 当 花 一 部 分 时 间 来 熟悉 这 些 文件 ， 并 详细 的 阅读 README.txt 文 件 。 


3.4 运行 演示 实例 
在 解压 的 文件 中 ， 有 一 个 实例 演示 应 用 包含 了 JFreeChart 产 生 的 大 量 图 表演 示 实 
例 。 输 入 下 面 命令 可 以 运行 该 应 用 : 


java -jar jfreechart-1.0.6-demo. jar 


实例 的 源 代码 跟 JFreeChart 开 发 指南 一 并 发 行 ， 是 收费 的 。 


3.5 编译 源 代 码 


我 们 可 是 使 用 ant 的 build.xml 文 件 重新 编译 JFreeChart 类 文件 。 进 入 ant 目 录 ， 然 后 
键入 : 


ant complie 


这 将 重新 编译 全 部 的 源 文件 和 创建 创建 JFreeChart 运 行 时 依赖 的 jar 文 件 。Ant 工 具 
需要 1.5.1 版 本 或 更 高 版 本 ， 我 们 可 以 从 下 面 链接 获得 更 多 ant 信 息 : 


http://ant.apache.org/ 


3.6 > javadoc x 7% 


JFreeChart 源 代码 文件 中 包含 了 大 量 丰 富 的 Javadoc 注 释 。 我 们 使 用 javadoc 工 具 可 
以 直接 从 源 代 码 中 产生 HTML 文 件 。 


产生 javadoc 文 件 使 用 ant 的 javadoc 目 标 ， 进 入 ant 目 录 键 入 : 


ant javadoc 


这 将 产生 javadoc 目 录 。 目 录 下 面包 含 了 全 部 的 Javadoc 的 HTML 文 件 。 


4 使 用 JFreeChart1.0.6 


4.1 概述 


JFreeChart 的 新 用 户 编 写 了 一 个 简单 的 实例 ， 以 说 明 JFreeChart 的 使 
方法 。 


4.2 创建 第 一 个 图 表 


4.2.1 概述 


使 用 JFreeChart 创 建 图 表 共有 三 个 步骤 。 如 下 : 

e 创建 一 个 dataset。 该 dataset 包 含 图 表 要 显示 的 数据 。 

° T o 。 该 对 象 负 责 画 这 个 图 表 。 

e 创建 一 个 输出 目标 (如 : 一 个 panel， 显 示 在 屏幕 上 ) 。 该 输出 目标 画 这 个 图 
表 o 


下 面 ， 我 们 使 用 一 个 简单 的 应 用 (First java) 来 描述 这 个 过 程 。 该 应 用 产生 了 一 个 
饼 图 ， 如 下 图 4.1 所 示 : 


Sample Pie Chart 


[atego 2] 








图 4.1 创建 的 第 一 个 饼 图 (参考 Firstjaval ) 
上 面 描述 的 三 个 步 又， 将 在 下 面 的 章节 里 面 ， 均 有 代码 详细 说 明 。 


4.2.2 数据 


步骤 一 要 求 我 们 为 我 们 的 图 表 创建 一 个 dataset。 使 用 DefaultPieDataset 类 可 以 很 容 
易 创 建 。 如 下 代码 : 


// create a dataset... 

DefaultPieDataset dataset = new DefaultPieDataset(); 
dataset.setValue("Category 1", 43.2); 
dataset.setValue("Category 2", 27.9); 
dataset.setValue("Category 3", 79.5); 


JFreeChart 可 以 使 用 符合 PieDataset 接 口 的 任何 实现 数据 来 创建 饼 图 。 
DefaultDataset 类 实现 了 PieDataset 接 口 ， 提 供 了 一 种 便利 的 使 用 方式 。 


我 们 可 以 自由 的 开发 符合 实际 需 的 任意 PieDataset 接 口 实 现 。 


4.2.3 创建 一 个 饼 图 


步骤 二 关心 的 是 我 们 如 何 使 用 这 个 dataset 展 示 在 区 域 中 。 这 就 需要 我 们 创建 一 个 
JFreeChart 对 象 ， 该 对 象 使 用 我 们 的 饼 图 dataset 数 据 画 一 个 图 表 。 我 们 使 用 
ChartFactory 类 来 创建 ， 代 码 如 下 : 


// create a chart... 
JFreeChart chart = ChartFactory.createPieChart ( 
"Sample Pie Chart", 
dataset, 
true, // legend? 
true, // tooltips? 
false // URLs? 


) 


注意 : 

代码 中 将 一 个 dataset 的 引用 传 入 到 工厂 方法 中 。JFreeChart 持 有 这 个 dataset 引 用 

的 目的 是 便于 在 画图 表 时 能 够 获得 数据 。 使 用 JFreeChart 创 建 图 表 有 许多 定制 外 观 

的 方式 ， 在 这 个 例子 中 我 们 使 用 缺 省 的 属性 值 。 后 面 章 节 将 详细 介绍 。 

4.2.4 显示 图 表 

最 好 一 个 步骤 就 是 在 某 个 地 方 显示 该 图 表 。JFreeChart 提 供 了 非常 灵活 的 图 表 输 出 

现在 我 们 可 以 在 一 个 屏幕 的 框架 中 显示 这 个 图 表 。ChartFrame 具 有 显示 图 表 的 机 制 
(ChartPanel) 。 代 码 如 下 : 


// create and display a frame... 

ChartFrame frame = new ChartFrame("First", chart); 
frame.pack(); 

frame.setVisible(true); 


代码 全 部 完成 ， 运 行 main() 方 法 ,可 以 出 现 图 4.1 界 面 。 


4.2.5 全 部 程序 代码 


下 面 是 整个 例子 的 全 部 代码 ， 更 加 清楚 的 看 到 我 们 需要 导入 的 类 包 和 实现 方法 。 


public class First { 
public static void main(String[] args) { 
// create a dataset... 
DefaultPieDataset dataset = new DefaultPieDataset(); 
dataset.setValue("Category 1", 43.2); 
dataset.setValue("Category 2", 27.9); 
dataset.setValue("Category 3", 79.5); 
// create a chart... 
JFreeChart chart = ChartFactory.createPieChart ( 
"Sample Pie Chart", 
dataset, 
true, // legend? 
true, // tooltips? 
false // URLS? 
); 
// create and display a frame... 
ChartFrame frame = new ChartFrame("First", chart); 
frame.pack(); 
frame.setVisible(true); 


5 4+ (Pie Charts) 


5.1 简介 
本 章 主要 讲解 JFreeChart 中 饼 图 的 一 些 特征 。 内 容 如 下 : 


42 tl MR E40 A Bb Rp 

null 4a fe 2 4a hy 2b HE 

饼 图 片区 的 标签 【定制 文本 ， 改 变 分 配 的 比例 空间 ) 
“取出 ” 茶 个 片区 

多 个 饼 图 显示 

显示 3D 效 果 的 饼 图 


更 多 的 信息 ， 可 以 参见 PiePlot 参 考 文档 ， 见 章节 33.72。 


5.2 创建 简单 的 饼 图 (Pie Charts ) 


在 前 面 的 第 四 章 的 手把手 的 向 导 里 创建 了 一 个 简单 的 饼 图 。 在 这 里 不 做 详细 介绍 。 


5.31 RARE 


饼 图 片区 缺 省 填充 的 顾 色 是 自动 分 配 的 ， 正 如 你 上 面 实例 看 到 的 。 如 果 你 不 喜欢 这 
个 缺 省 的 颜色 ， 你 可 以 实用 setSectionPaint () 方法 来 设置 片区 颜色 。 例 如 
PiePlot plot = 


(PiePlot) chart.getPlot(); 
plot.setSectionPaint("Section A", 


new Color(200, 255, 255)); 
plot.setSectionPaint("Section B", 


new Color(200, 200, 255)); 


JFreeChart 的 实例 PieChartDemo2.java 演 示 了 如 何 定 制 颜 色 。 在 JFreeChart 的 代码 
中 ， 片 区 颜色 使 用 三 层 色 属 性 机 制 来 定义 的 。 同 时 ， 我 们 也 可 以 对 饼 图 中 的 每 一 个 
系列 定义 填充 的 颜色 ， 这 里 我 们 不 做 细 述 ， 更 多 的 信息 请 参阅 PiePlot 类 (33.27% 
节 ) 。 


5.44 EIER 


每 一 个 人 饼 图 片区 的 外 廊 黑 认 是 一 条 细 灰 线 义 画 出 来 的 。PiePlot 类 提供 了 如 下 选 


项 
e 完全 不 显示 片区 外 廓 
e 通过 改变 缺 省 的 值 来 改变 全 部 的 片区 外 廓 
o 单独 改变 部 分 饼 图 的 片区 外 廊 

5.4.1 片区 外 廓 的 可 见 性 控制 

为 了 完全 关闭 片区 外 廓 ， 使 用 下 面 代码 : 


PiePlot plot = (PiePlot) chart.getPlot(); 
plot.setSectionOutlinesVisible(false) ; 


在 任何 时 候 ， 你 只 需要 使 用 下 面 代 码 可 以 让 外 万 显示 出 来 : 
plot.setSectionOutlinesVisible(true); 
调用 该 方法 可 以 触发 PlotChangeEvent 事 件 。 


5.4.2 片区 外 廊 的 控制 


择 


在 片区 外 廊 显 示 的 时 候 ， 我 们 可 以 改变 饼 图 片区 的 整个 外 廊 颜 色 或 风格 或 者 单个 饼 
图 片区 的 颜色 或 风格 。 整 个 外 廊 颜 色 或 风格 的 修改 需要 在 基本 层 里 面 设 置 ， 单 个 饼 
图 片区 的 颜色 设置 需要 在 系列 层 中 设置 。 在 基本 层 里 ， 如 果 没 有 更 高 层 的 颜色 设 
置 ， 则 调用 已 定义 的 默认 设置 。 我 们 可 以 使 用 PiePot 类 的 方法 来 改变 我 们 的 设置 。 


如 下 方法 : 


public void setBaseSectionOutlinePaint(Paint paint); 
public void setBaseSectionOutlineStroke(Stroke stroke); 


ARRAREN’ KMNSLEKKEHAZDRTPAAY HY BMPR > HK 


许 突出 显示 茶 些 片区 的 细节 方面 。 做 到 这 些 ， 我 们 可 以 是 使 用 系列 层 层 设置 ， 


下 面 的 方法 来 定义 。 


public void setSectionOutlinePaint(Comparable key, Paint paint); 
public void setSectionOutlineStroke(Comparable key, Stroke strok 


e); 


方法 的 第 一 个 参数 是 dataset 的 片区 关键 值 。 如 果 我 们 将 该 值 设 为 null， 则 系统 将 使 
用 基本 层 的 设置 。 


5.5 ZE ` Kii Fe f Ai 


PieDataset 可 能 会 包含 一 些 饼 图 不 可 能 显示 的 数值 ， 比 如 null、 零 值 或 者 负 值 。 对 
于 这 些 数据 PiePlot 类 有 专门 的 处 理 机 制 来 处 理 。 如 果 是 零 值 ， 并 且 该 值 有 意义 ， 
PiePlot 类 默认 将 一 个 标签 放置 在 饼 图 片区 显示 的 位 置 ， 并 且 在 图 表 的 图 例 中 添加 一 
个 分 类 。 如 果 零 值 可 以 忽略 ， 我 们 可 以 使 用 下 面 代码 设置 一 个 标志 ， 不 显示 该 数 
35 : 


PiePlot plot = (PiePlot) chart.getPlot(); 
plot .setIgnorezZeroValues(true); 


类 似 的 null 值 也 是 如 此 处 理 ，nul 值 代表 dataset 丢 失 或 者 不 知 来 源 的 值 。 缺 省 的 处 理 
与 零 值 相同 ， 如 果 忽 略 null 值 ， 则 代码 如 下 : 


PiePlot plot = (PiePlot) chart.getPlot(); 
plot.setIgnoreNullValues(true); 


在 饼 图 中 处 理 负 值 是 非常 不 明知 的 ， 所 以 在 JFreeChart 中 负 值 总 是 被 忽略 的 。 


5.6 片区 和 图 例 标 签 


片区 标签 使 用 的 文本 ， 即 可 以 在 图 表 上 显示 ， 也 可 以 在 图 表 的 图 例 上 显示 ， 并 且 完 
全 可 以 定制 。 标 签 是 自动 默认 产生 的 ， 但 我 们 可 以 使 用 下 面 方法 来 改变 : 


public void setLabelGenerator(PieSectionLabelGenerator generator 


了 
public void setLegendLabelGenerator(PieSectionLabelGenerator gen 
erator); 


StandPieSectionLabelGenerator 类 专门 用 来 生成 图 例 的 一 个 实现 类 ， 提 供 灵 活 处 理 
定制 标签 的 功能 (如果 你 不 喜欢 用 这 个 类 ， 可 以 定义 自己 的 类 ， 只 要 实现 接口 
PieSectionLabelGenerator 即 可 ) 。Dataset 显 示 出 的 标签 值 由 Javade 信 息 格式 类 来 
进行 格式 化 一 一 表 5.1 所 示 格 式 化 的 变量 值 。 


名 称 描述 
{0} 片区 关键 值 (FHF) 
{1} 片区 值 
{2} 百分比 的 片区 值 


表 5.1 StandardPieSectionLabelGenerator substitutions 


下 面 举例 说 ， 假 如 我 们 有 一 个 PieData 包 含 下 面 的 值 


片区 标识 片区 值 
S1 3.0 
S2 5.0 
S3 Null 
S4 2.0 


表 5.2 一 个 dataset 实 例 
下 面 是 格式 化 字符 串 产 生 的 标签 值 内 容 : 


格式 化 字符 串 片区 产生 的 标签 值 


{0} 0 S1 
{0} has value {1} 1 S2 has value 5.0 
{0}({2} percent) 0 $1(30 percent) 
{0} = {1} 2 S3 = null 


类 PieChartDemo2.java 使 用 了 定制 标签 的 方法 。 


5.7“ 取 出 ” 茶 个 片区 


PiePlot 类 支持 将 某 个 片区 “取出 “显示 。 即 某 个 片区 偏离 图 表 中 心 ， 以 突出 显示 。 如 
类 所 显示 。 


片区 偏离 的 数值 是 图 表 半 径 的 一 个 百 分 值 来 表示 。 例 如 0.3 (30 persent) 代码 偏离 
的 值 是 半径 的 长 度 x0.3. 代 码 如 下 : 


PiePlot pieplot = (PiePlot) jfreechart.getPlot(); 
pieplot.setExplodePercent("Two", 0.5); 


5.8 3D 人 饼 图 


JFreeChart 具 有 一 个 实现 3D 效 果 的 饼 图 类 PiePlot3D， 如 图 5.5 所 示 ， 
(PieChart3DDemo1.java)。PiePlot3D 是 PiePlot 的 子 类 ， 因 此 在 我 们 创建 自己 的 饼 
图 时 ， 使 用 PiePlot3D 替 换 掉 原来 的 PiePlot 即 可 。 创 建 3D 效 果 的 饼 图 时 ， 使 用 
ChartFactory 的 createPieChart3D () 方法 ， 而 不 是 createPieChart () 方法 。 


2 Pie Chart 3D Demo 1 同上 回回 
Pie Chart 3D Demo 1 





如 5.5 3D 效 果 图 。 
对 于 该 类 有 一 些 限 制 ， 如 下 : 
o 不 支持 "取出 ”片区 功能 。 


© 不 支持 轴 项 转动 一 如 果 支 持 ，3D 效 果 图 可 能 会 变型 。 


3D 的 实例 主要 是 类 PieChart3DDemo1-3.java。 讲 解 类 中 没有 列 出 其 他 两 个 。 因 为 
功能 雷同 于 非 3D 效 果 。 
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5.9 5A 


我 们 可 是 使 用 类 MultiplePiePlot 在 一 个 图 表 上 显示 多 个 饼 图 。 人 饼 图 的 数据 使 用 
CatoryDataset。 如 图 5.6 所 示 。 每 个 独立 的 饼 图 由 一 个 专门 的 图 表 多 次 创建 而 成 。 
创建 的 每 一 个 饼 图 的 PieDataset 是 由 系统 提供 的 CategoryDataset 按 照 行 或 者 列 拆 分 
出 来 的 。 代 码 见 5.10.11. 


> Multiple Pie Chart Demo 1 


Multiple Pie Chart 














图 5.6 多 饼 图 图 表 
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5.10 实例 讲解 


5.10.1 体会 
也 分 为 三 层 界面 显示 层 、 数 据 层 、 控 制 层 。 


o 数据 层 比 较 复 杂 。 每 个 图 形 有 不 同 的 数据 类 型 。Dataset 类 控制 。 

控制 层 Plot， 人 饼 图 使 用 PiePlot 设 置 显示 的 图 形 的 面貌 的 控制 ，JFreeChart 最 丰 
富 的 功能 。 

Khe kh BRE 

设置 标签 (文本 格式 、 背 景 凑 色 等 ) 

设置 是 否 取出 某 块 。 

设置 饼 图 是 否 为 圆 形 

设置 饼 图 旋转 。 

显示 层 JFreeChart 使 用 数据 、 控 制 直接 将 数据 显示 出 来 。 


5.10.2 类 PieChartDemo1.java 
效果 图 如 下 : 


Pie Chart Deao 1 TBR) 
Pie Chart Demo 1 





Three 
@ One @ Two ® Three © Four @ Five © Six 


代码 编写 典型 的 使 用 了 面 对 对 象 的 方法 : 




















P EC harD em ol 


man 


Dem ol {P E ChartD em o 1”) 





creatD atiset 


全 部 代码 如 下 : 


package demo; 
java.awt.Dimension; 
java.awt.Font; 
javax.Swing.JPanel; 


import 
import 
import 
import 
import 
import 
import 
import 
import 
import 
import 
import 
public 


[Por 


* 


i 


org.jfree. 
org.jfree. 
org.jfree. 
org.jfree. 
org.jfree. 
org.jfree. 
org.jfree. 
org.jfree. 
org.jfree. 


ateD em oP ane 10 


chart 
chart 


chart. 
chart. 
chart. 


.ChartFactory; 
.ChartPanel; 


JFreeChart; 
plot .PiePlot; 
title.TextTitle; 


data.general.DefaultPieDataset; 
data.general.PieDataset; 
ui.ApplicationFrame; 
ui.RefineryUtilities; 

class PieChartDemo1 extends ApplicationFrame { 


private static final long serialVersionUID = 259855755772408 


5474L; 


public PieChartDemo1(String string) { 
super(string); 
JPanel jpanel = createDemoPanel(); 

jpanel.setPreferredSize(new Dimension(500, 270)); 


setContentPane(jpanel); 


} 


private static PieDataset createDataset() { 


DefaultPieDataset 
set(); 


defaultpiedataset. 
defaultpiedataset. 
.setValue("Three", new Double(27.5)); 
defaultpiedataset. 
defaultpiedataset. 
defaultpiedataset. 


defaultpiedataset 


defaultpiedataset = new DefaultPieData 


setValue("One", new Double(43.2)); 
setValue("Two", new Double(10.0)); 


setValue("Four", new Double(17.5)); 
setValue("Five", new Double(11.0)); 
setValue("Six", new Double(19.4)); 


return defaultpiedataset; 


} 


private static JFreeChart createChart(PieDataset piedataset ) 


{ 


JFreeChart jfreechart = ChartFactory.createPieChart("Pie 


Chart Demo i", 
piedataset, true, 


true, false); 


TextTitle texttitle = jfreechart.getTitle(); 
texttitle.setToolTipText("A title tooltip!"); 


PiePlot pieplot = 


(PiePlot) jfreechart.getPlot(); 


pieplot.setLabelFont(new Font("Arial Black", ©, 20)); 
pieplot.setNoDataMessage("No data available"); 
pieplot.setCircular(false); 
pieplot.setLabelGap(0.02); 


return jfreechart; 


} 


public static JPanel createDemoPanel() { 
JFreeChart jfreechart = createChart(createDataset()); 
return new ChartPanel(jfreechart); 


} 


public static void main(String[] strings) { 
PieChartDemo1 piechartdemo1 = new PieChartDemo1("Pie Cha 


rt Demo 1"); 


piechartdemo1.pack(); 
RefineryUtilities.centerFrame0nScreen(piechartdemo1); 
piechartdemo1.setVisible(true); 


5.10.3 类 PieChartDemo2.java 


功能 : 
“取出 “片区 显示 。 
效果 : 


' Pie Chart Demo 2 TBR) 


Pie Chart Demo 2 
Seven (0% 
percent) \ 


Four(14% ee 
percent) 
Three (21% 
percent) 


One @ Two @ Three @ Four @ Five @ Six @ Seven 


Two (8% percent) 





代码 : 


private static JFreeChart createChart(PieDataset piedataset) { 
JFreeChart jfreechart = ChartFactory.createPieChart("PieChar 
t Demo 2", piedataset, true, true, false); 
PiePlot pieplot = (PiePlot) jfreechart.getPlot(); 
pieplot.setSectionPaint("One", new Color(160, 160, 255)); 
pieplot.setSectionPaint("Two", new Color(128, 128, 223)); 
pieplot.setSectionPaint("Three", new Color(96, 96, 191)); 
pieplot.setSectionPaint("Four", new Color(64, 64, 159)); 
pieplot.setSectionPaint("Five", new Color(32, 32, 127)); 
pieplot.setSectionPaint("Six", new Color(0, 0, 111)); 
pieplot.setNoDataMessage("No data available"); 
pieplot.setExplodePercent("Two", 0.5); 
pieplot.setLabelGenerator(new StandardPieSectionLabelGenerat 
or("{0} ({2} percent)")); 
pieplot.setLabelBackgroundPaint(new Color(220, 220, 220)); 
pieplot.setLegendLabelToolTipGenerator(new StandardPieSectio 
nLabelGenerator("Tooltip for legend item {0}")); 
return jfreechart; 
} 


程序 代码 说 明 : 


e setSectionPaint("One", new Color(160, 160, 255)) : 设置 某 个 片区 
的 填充 颜色 。 第 一 个 参数 为 片区 的 标识 ， 第 二 个 参数 为 色 值 。 

e setNoDataMessage("No data available") : 设置 dataset 为 null 时 显示 的 
提示 信息 。 

setLabelGenerator(new StandardPieSectionLabelGenerator("{0}({2} 
: 设置 标签 显示 的 格式 。 

setLabelBackgroundPaint(new Color(220, 220, 220)) : 设置 标签 的 背 
景 颜色 。 
e setLegendLabelToolTipGenerator(new StandardPieSectionLabelGeneré 


: 设置 鼠标 滑 过 图 表 是 显示 鼠标 当前 片区 的 提示 信息 。 
e pieplot.setExplodePercent("Two", 0.5) :将 第 2 个 片区 取出 显示 。 后 面 
一 个 参数 是 取出 的 距离 ， 是 一 个 比例 数 。 


5.10.4 类 PieChartDemo3.java 
功能 : 


显示 了 dataset 为 空 时 ， 设 置 的 提示 信息 。 


Pie Chart Demo 3 


没有 有 效 的 数据 显示 ! 








代码 : 


private static JFreeChart createChart(PieDataset piedataset) { 
JFreeChart jfreechart = ChartFactory.createPieChart("Pie Cha 
rt Demo 3", 
null, true, true, false); 
PiePlot pieplot = (PiePlot) jfreechart.getPlot(); 
pieplot.setNoDataMessage("A A AN RGE BRI"); 
pieplot .setNoDataMessageFont(new Font("A%k", 2, 20)); 
pieplot.setNoDataMessagePaint(Color.red); 
return jfreechart; 


程序 代码 说 明 : 


e SetNoDataMessage(" 没 有 有 效 的 数据 显示 !") : 设置 提示 信息 内 容 。 

e setNoDataMessageFont(new Font("Serif", 2, 10)) :设置 提示 信息 的 
字体 和 大 小 。 

e setNoDataMessagePaint(Color.red) : 设置 提示 信息 字体 的 颜色 。 


5.10 实例 讲解 


5.10.5 类 PieChartDemo4.java 

功能 : 

带 有 按钮 的 图 表 ， 通 过 对 dataset 的 排序 ， 可 以 改变 片区 的 位 置 。 
效果 : 


= Pie Chart Demo 4 
Pie Chart Demo 4 














& Section A @ Section B ® Section C © Section D ® Section E © Section F 


By Key By Value Random 








代码 : 
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public void actionPerformed(ActionEvent actionevent) { 
String string = actionevent.getActionCommand(); 
if ("BY_KEY".equals(string)) { 
if (!ascendingByKey) { 
dataset.sortByKeys(SortOrder .ASCENDING) ; 
ascendingByKey = true; 
} else { 
dataset.sortByKeys(SortOrder .DESCENDING); 
ascendingByKey = false; 


} 
} else if ("BY_VALUE".equals(string)) { 

if (!ascendingByValue) { 
dataset.sortByValues(SortOrder .ASCENDING) ; 
ascendingByValue = true; 

} else { 
dataset.sortByValues(SortOrder .DESCENDING) ; 
ascendingByValue = false; 


} 
} else if ("RANDOM".equals(string)) { 
ArrayList arraylist = new ArrayList(dataset.getKeys()); 
Collections.shuffle(arraylist); 
DefaultPieDataset defaultpiedataset = new DefaultPieData 
set(); 
Iterator iterator = arraylist.iterator(); 
while (iterator.hasNext()) { 
Comparable comparable = (Comparable) iterator.next() 


defaultpiedataset.setValue(comparable, dataset 
.getValue(comparable) ); 


} 
PiePlot pieplot = (PiePlot) chart.getPlot(); 


pieplot.setDataset(defaultpiedataset); 
dataset = defaultpiedataset; 


程序 代码 说 明 : 


e dataset.sortByKeys(SortOrder .ASCENDING); 通过 片区 的 关键 值 进行 升序 
排序 。 

e dataset.sortByValues(SortOrder.DESCENDING); 通过 片区 的 值 进行 降序 
排序 。 


5.10.6 类 PieChartDemo5.java 

功能 : 

右边 两 个 人 饼 图 为 原形 的 ， 而 左边 两 个 为 椭圆 形 的 。 
效果 : 


: Pie Chart Demo 5 TER) 
Chart 1 Chart 2 


setCirculartrue); setCirculanfalse); 

















Chart 3 Chart 4 


setCircular(true); setCirculanfalse); 





代码 : 


public static JPanel createDemoPanel() { 
JPanel jpanel = new JPanel(new GridLayout(2, 2)); 
DefaultPieDataset defaultpiedataset = new DefaultPieDataset( 
); 
defaultpiedataset.setValue("Section 1", 23.3); 
defaultpiedataset.setValue("Section 2", 56.5); 
defaultpiedataset.setValue("Section 3", 43.3); 
defaultpiedataset.setValue("Section 4", 11.1); 
// 
JFreeChart jfreechart = ChartFactory.createPieChart("Chart 1 


defaultpiedataset, false, false, false); 
jfreechart.addSubtitle(new TextTitle("setCircular(true);", n 
ew Font( 
"Dialog", ©, 12))); 
PiePlot pieplot = (PiePlot) jfreechart.getPlot(); 
pieplot.setCircular(true); 
// 
JFreeChart jfreechart 0 = ChartFactory.createPieChart("Char 
t Zu 
defaultpiedataset, false, false, false); 
jfreechart 0_ .addSubtitle(new TextTitle("setCircular(false); 


new Font("Dialog", ©, 12))); 
PiePlot pieplot 1 = (PiePlot) jfreechart_O_.getPlot(); 
pieplot_1_.setCircular(false); 
// 


JFreeChart jfreechart_2_ = ChartFactory.createPieChart3D("Ch 


are ou 


defaultpiedataset, false, false, false); 
jfreechart_2_.addSubtitle(new TextTitle("setCircular(true);" 


, new Font( 


"Dialog", ©, 12))); 
PiePlot3D pieplot3d = (PiePlot3D) jfreechart_2_.getPlot(); 
pieplot3d.setForegroundAlpha(0.6F); 
pieplot3d.setCircular (true); 
// 
JFreeChart jfreechart_3_ = ChartFactory.createPieChart3D("Ch 


art 4", 


defaultpiedataset, false, false, false); 
jfreechart_3_.addSubtitle(new TextTitle("setCircular(false); 


new Font("Dialog", ©, 12))); 
PiePlot3D pieplot3d_4 = (PiePlot3D) jfreechart_3_.getPlot() 


pieplot3d_4 _.setForegroundAlpha(0.6F); 
pieplot3d_4 _.setCircular(false); 

jpanel.add(new ChartPanel(jfreechart)); 
jpanel.add(new ChartPanel(jfreechart_0_)); 
jpanel.add(new ChartPanel(jfreechart_2_)); 
jpanel.add(new ChartPanel(jfreechart_3_)); 
jpanel.setPreferredSize(new Dimension(800, 600)); 
return jpanel; 


程序 代码 说 明 : 


pieplot.setCircular(true) :设置 饼 图 为 圆 形 。 
jpanel.add 方法 可 以 添加 多 个 图 形 的 panel 


5.10.7 类 PieChartDemo6.java 


人 饼 图 对 零 值 和 null 值 的 处 理 。 


2 Pie Chart Demo 6 


Pie Chart 1 


Ignore nulls: false; Ignore zeros: false; 


= null 


Pie Chart 3 


Ignore nulls: false; Ignore zeros: true; 








Pie Chart 2 


Ignore nulls: true; Ignore zeros: false; 


S20 


Pie Chart 4 


Ignore nulls: true; ignore zeros: true; 





代码 : 


jest © s4] 
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public static JPanel createDemoPanel() { 
JPanel jpanel = new JPanel(new GridLayout(2, 2)); 
JFreeChart jfreechart = createChart("Pie Chart 1", createDat 
aset()); 
Font font = new Font("Dialog", 0, 12); 
jfreechart.addSubtitle(new TextTitle( 
"Ignore nulls: false; Ignore zeros: false;", font)); 
JFreeChart jfreechart_ 0 = createChart("Pie Chart 2", create 
Dataset()); 
jfreechart_O0_.addSubtitle(new TextTitle( 
"Ignore nulls: true; Ignore zeros: false;", font)); 
PiePlot pieplot = (PiePlot) jfreechart_O_.getPlot(); 
pieplot.setIgnoreNullValues(true); 
pieplot.setIgnoreZeroValues(false); 
JFreeChart jfreechart_1_ = createChart("Pie Chart 3", create 
Dataset()); 
jfreechart_1_.addSubtitle(new TextTitle( 
"Ignore nulls: false; Ignore zeros: true;", font)); 
PiePlot pieplot_2_ = (PiePlot) jfreechart_1_.getPlot(); 
pieplot_2_.setIgnoreNullValues(false); 
pieplot_2_.setIgnoreZeroValues(true); 
JFreeChart jfreechart_3_ = createChart("Pie Chart 4", create 
Dataset()); 
jfreechart_3_.addSubtitle(new TextTitle( 
"Ignore nulls: true; Ignore zeros: true;", font)); 
PiePlot pieplot 4 = (PiePlot) jfreechart_3_.getPlot(); 
pieplot_4_.setIgnoreNullValues(true); 
pieplot_4_.setIgnoreZeroValues(true); 
jpanel.add(new ChartPanel(jfreechart)); 
jpanel.add(new ChartPanel(jfreechart_O0_)); 
jpanel.add(new ChartPanel(jfreechart_1_)); 
jpanel.add(new ChartPanel(jfreechart_3_)); 
return jpanel; 


程序 代码 说 明 : 


4 


e pieplot.setIgnoreNullValues(true) : 设置 饼 图 忽略 null 值 ， 即 是 null 值 
将 不 显示 。 

e pieplot.setIgnoreZeroValues(false); 设置 饼 图 不 忽略 零 值 。 即 图 表 中 
显示 h RE 3 


5.10.8 类 PieChartDemo7.java 
功能 : 

图 表 能 够 旋转 ， 标 签 也 随 之 移动 。 
效果 : 


' Pie Chart Demo 7 
Pie Chart Demo 7 


Section 9 = 11% | 
f Section 10= 11% 


Section 8 = 11% 

Section 11 = 8% 
Section 7 = 3% 广 一 一 
Section6=6% 


Section 4= 1% 4 Section 0 = 1% 
Section 3 = 8% o ~ Section 1 = 10% 


[Section 2= 1%) 











代码 : 


public static JPanel createDemoPanel() { 
PieDataset piedataset = createDataset(14); 
JFreeChart jfreechart ChartFactory.createPieChart("Pie Cha 
rt Demo 7", 
piedataset, false, true, false); 
jfreechart.setBackgroundPaint(new Color(222, 222, 255)); 
PiePlot pieplot = (PiePlot) jfreechart.getPlot(); 
pieplot .setBackgroundPaint(Color.white); 
pieplot.setCircular(true); 
pieplot.setLabelGenerator(new StandardPieSectionLabelGenerat 


or( 
"{0} = {2}", NumberFormat.getNumberInstance(), NumberFor 
mat 
.getPercentInstance())); 
pieplot.setNoDataMessage("No data available"); 
ChartPanel chartpanel = new ChartPanel(jfreechart); 
chartpanel.setPreferredSize(new Dimension(500, 270)); 
Rotator rotator = new Rotator(pieplot); 
rotator.start(); 
return chartpanel; 
} 
程序 代码 说 明 : 


e 使 用 Rotator 对 象 ， 旋 转 饼 图 。 代 码 如 上 。 


5.10.9 PieChartDemo8.java 


编写 自 定 义 标 签 产生 器 ， 将 Two 标签 不 显示 。 


Pie Chart Demo 8 TBR) 
Pie Chart Demo 8 








代码 : 


private static JFreeChart createChart(PieDataset piedataset) { 
JFreeChart jfreechart = ChartFactory.createPieChart("Pie Cha 
rt Demo 8", 
piedataset, false, true, false); 
PiePlot pieplot = (PiePlot) jfreechart.getPlot(); 
pieplot.setLabelGenerator(new CustomLabelGenerator()); 
return jfreechart; 
} 
static class CustomLabelGenerator implements PieSectionLabelGene 
rator { 
public String generateSectionLabel(PieDataset piedataset, 
Comparable comparable) { 
String string = null; 
if (piedataset != null && !comparable.equals("Two" ) ) 
string = comparable.toString(); 
return string; 


public AttributedString generateAttributedSectionLabel ( 

PieDataset piedataset, Comparable comparable) { 

Object object = null; 

String string = comparable.toString(); 

String string 0 = (string + " : " + String.valueOf (pied 
ataset 

.getValue(comparable) )); 

AttributedString attributedstring = new AttributedString 
(string_0_); 

attributedstring.addAttribute(TextAttribute.WEIGHT, 

TextAttribute.WEIGHT_BOLD, 0, string.length() - 1); 

return attributedstring; 


程序 代码 说 明 : 


e 自 定 义 CustomLabelGenerator ， 必 须 实现 接 
€ PieSectionLabelGenerator ° 


5.10.10 PieChart3DDemo1.java 
功能 : 


3D 效 果 的 饼 图 。 


回回 加 
Pie Chart 3D Demo 1 


® Java @ Visual Basic ® C/C++ © PHP ® Perl 





代码 : 


private static JFreeChart createChart(PieDataset piedataset) { 

JFreeChart jfreechart = ChartFactory.createPieChart3D/( 
"Pie Chart 3D Demo 1", piedataset, true, true, false); 

PiePlot3D pieplot3d = (PiePlot3D) jfreechart.getPlot(); 
pieplot3d.setStartAngle(180.0); 
pieplot3d.setDirection(Rotation.CLOCKWISE) ; 
pieplot3d.setForegroundAlpha(0.5F); 
pieplot3d.setNoDataMessage("No data to display"); 
return jfreechart; 


程序 代码 说 明 : 


使 用 ChartFactory 的 方法 createPieChart3D 创建 3D 效 果 的 饼 图 。 
setStartAngle(180.0) : 设置 旋转 角度 。 
setDirection(Rotation.CLOCKWISE) : 设置 旋转 方 
向 ， Rotation.CLOCKWISE 为 顺 时 针 。 
setForegroundAlpha(0.5F) : 设置 图 表 透 明 图 0.0~1.0 范 围 。0.0 为 完全 透 


Te) 


明 ，1.0 为 完全 不 透明 。 
5.10.11 类 MultiplePieChartDemo1.java 


功能 : 


使 用 CategoryDataset 数 据 集 ， 在 一 个 图 表 上 产生 多 个 饼 图 。 











@ Sales/Q1 @Sales/Q2 ® Sales/Q3  Sales/Q4 


代码 : 


private static CategoryDataset createDataset() { 
double[][] ds = { { 3.0, 4.0, 3.0, 5.0 }, { 5.0, 7.0, 6.0, 8 
:0 }, 
{ 5.0, 7.0, Double.NaN, 3.0 }, { 1.0, 2.0, 3.0, 4.0 }, 
{ 2.0, 3.0, 2.0, 3.0} }; 
CategoryDataset categorydataset = DatasetUtilities 
.createCategoryDataset("Region ", "Sales/Q", ds); 
return categorydataset; 


程序 代码 说 明 : 


e 创建 CategoryDataset 的 方法 。 


private static JFreeChart createChart(CategoryDataset categoryda 
taset) { 

JFreeChart jfreechart = ChartFactory.createMultiplePieChart ( 

"Multiple Pie Chart", categorydataset, TableOrder.BY_ROW 

, true, true, false); 

MultiplePiePlot multiplepieplot = (MultiplePiePlot) jfreecha 
rt .getPlot(); 

JFreeChart jfreechart © = multiplepieplot.getPieChart(); 

PiePlot pieplot = (PiePlot) jfreechart_O0_.getPlot(); 

pieplot.setLabelGenerator(new StandardPieSectionLabelGenerat 
or("{0}")); 

pieplot.setLabelFont(new Font("SansSerif", ©, 8)); 

pieplot.setInteriorGap(0.3); 

return jfreechart; 


程序 代码 说 明 : 


e 使 用 ChartFactory 的 方法 createMultiplePieChart() 创建 多 个 饼 图 的 图 
表 。 
e multiplepieplot.getPieChart() : 获得 单个 饼 图 的 图 表 。 


图 (Bar Charts) 


6.1 简介 


本 章 详细 介绍 了 使 用 JFreeChart 创 建 直方 条 形 图 的 过 程 。 开 始 我 们 先 用 一 个 简单 的 
直方 条 形 图 例子 进行 说 明 ， 然 后 进一步 深入 了 解 JFreeChart 为 直方 条 形 图 提供 的 定 
制 方法 。 在 了 解 了 这 些 标 准 的 直方 条 形 图 配置 项 之 后 ， 然 后 再 深入 了 解 更 复杂 的 图 
表 : 


o 堆栈 式 直方 条 形 图 
o 时 序数 据 的 条 形 直方 图 
e 柱状 图 


本 章 结束 之 后 ， 我 们 将 会 对 JFreeChart 支 持 直 方 条 形 图 创建 的 特点 有 个 整体 的 了 
解 。 


6.2 创建 一 个 直方 条 形 图 


6.2.1 概述 
直方 条 形 图 常常 被 用 来 显示 表 列 数据 。 如 下 表 ， 为 一 个 简单 的 两 行 、 三 列 数据 。 
表 6.1 

Colnums1 Colnums2 Colnums3 


Row1 10 5.0 3.0 
Row2 2.0 3.0 210 


在 JFreeChart 里 ， 这 个 表格 数据 封装 为 一 个 dataset 数 据 对 象 ， 每 列 标题 为 一 个 种 
类 ， 每 行为 一 个 系列 。 每 行 标题 为 一 个 系列 名 称 (或 者 系列 关键 值 ) 。 直 方 条 形 图 
展现 的 数据 图 如 图 6.2. 


= Simple Bar Chart 同上 回回 
Simple Bar Chart 





Column 1 Column 2 Column 3 








category 
图 6.2 简单 的 直方 条 形 图 (参见 : BarExample( java) 
在 这 个 图 表 的 实例 中 ， 我 们 可 以 看 到 JFreeChart 将 每 列 数据 ( 即 一 个 种 类 ) 组 合 在 
显示 


一 起 。 而 且 对 每 行 数据 ( 即 每 个 系列 ) 使 用 各 种 颜色 高 完 显 示 。 图 表 的 图 例 将 颜色 
和 系列 的 名 称 /关键 值 对 应 起 来 。 





6.2.2 创 一 个 dataset 


创建 直方 条 形 图 的 第 一 步 就 是 创建 一 个 合适 适 的 dataset 数 据 集 。 JFreeChart 为 直方 条 
形 图 提供 的 访问 表 列 数据 的 一 系列 方法 ， 必 须 符 合 接 口 CategoryDataset 定 义 。 


JFreeChart 中 提供 了 一 个 便利 的 实现 CategoryDataset 接 口 的 类 为 
DefaultCategoryDataset。 下 面 显示 我 们 如 何 使 用 这 个 类 来 封装 表 6.1 数 据 。 代 码 如 
下 : 


private CategoryDataset createDataset() { 
DefaultCategoryDataset dataset = new DefaultCategoryDataset ( 


); 


dataset.addValue(1.0, "Row 1", "Column 1"); 
dataset.addValue(5.0, "Row 1", "Column 2"); 
dataset.addValue(3.0, "Row 1", "Column 3"); 
dataset.addValue(2.0, "Row 2", "Column 1"); 
dataset.addValue(3.0, "Row 2", "Column 2"); 
dataset.addValue(2.0, "Row 2", "Column 3"); 


return dataset; 


6.2.3 创建 一 个 chart 图 表 


接 下 来 就 是 要 创建 一 个 JFreeChart 的 实例 ， 使 用 o 的 dataset 数 据 集 画 一 个 直 
方 条 形 图 。 简 单 的 ， 我 们 使 用 ChartFactory 类 来 创建 这 个 JFreeChart 实 例 。 代 码 如 
F 


private JFreeChart createChart(CategoryDataset dataset) { 
JFreeChart chart = ChartFactory.createBarChart ( 
"BarChartDemo", // chart title 
"Category", // domain axis label 
"Value", // range axis label 
dataset, // data 
PlotOrientation.VERTICAL, // orientation 
true, // include legend 
true, // tooltips? 
false // URLs? 
); 


return chart; 


CreateBarChart() i A #8 7 & HK 7a LHR Fy EB o (2 PBR pk HB — Hi 
明 o 


。 图 显示 的 方向 可 以 是 水 平 的 ， 还 是 可 以 是 重 直 的 。 

© 图表 的 信息 提示 ， 是 否 要 添加 ， 有 一 个 标志 来 控 制 一 一 在 上 面 的 例子 中 ， 我 们 
因此 当 我 们 在 一 个 swing 应 用 窗口 显示 这 个 图 表 时 ， 我 
们 会 看 到 这 个 信息 提示 8 

e URLs 标 志 ， 设置 为 false o 


我 们 完成 这 个 直方 条 形 图 后 ， 我 们 将 会 过 头 来 ， 仔 细 看 看 ChartFactory 类 在 后 台 做 
了 写 什 么 


6.2.4 显示 该 chart 图 表 


为 了 完成 我 们 的 第 一 个 直方 条 形 图 实例 ， 我 们 将 JFreeChart 实 例 传 给 一 个 
ChartPanel 对 象 ， 然 后 在 一 个 Swing 应 用 窗口 上 显示 该 实例 。 全 部 的 代码 如 下 


import java.awt.Dimension; 

import org.jfree.chart.ChartFactory; 

import org.jfree.chart.ChartPanel; 

import org.jfree.chart.JFreeChart; 

import org.jfree.chart.plot.PlotOrientation; 

import org.jfree.data.category.DefaultCategoryDataset; 
import org.jfree.ui.ApplicationFrame; 

import org.jfree.ui.RefineryUtilities; 

[fre 

* A simple demonstration application showing how to create a bar 
chart. 


“y 
public class BarExample1 extends ApplicationFrame { 
JEE 
* Creates a new demo instance. 
* 
* @param title 
* the frame title. 
Bh 
public BarExample1(String title) { 
super(title); 
DefaultCategoryDataset dataset = new DefaultCategoryData 
set(); 
dataset.addValue(1.0, "Row 1", "Column 1"); 
dataset.addValue(5.0, "Row 1", "Column 2"); 
dataset.addValue(3.0, "Row 1", "Column 3"); 
dataset.addValue(2.0, "Row 2", "Column 1"); 
dataset.addValue(3.0, "Row 2", "Column 2"); 
dataset.addValue(2.0, "Row 2", "Column 3"); 
JFreeChart chart = ChartFactory.createBarChart ( 


"Bar Chart Demo", // chart 

// title 

"Category", // domain axis label 

"Value", // range axis label 

dataset, // data 

PlotOrientation.VERTICAL, // orientation 

true, // include legend 

true, // tooltips? 

false // URLS? 
); 
ChartPanel chartPanel = new ChartPanel(chart, false); 
chartPanel.setPreferredSize(new Dimension(500, 270)); 
setContentPane(chartPanel); 


Starting point for the demonstration application. 


@param args 
ignored. 


+ + * F+W 
+ 
+ 


a 

public static void main(String[] args) { 
BarExample1 demo = new BarExample1("Bar Demo 1"); 
demo.pack(); 
RefineryUtilities.centerFrameOnScreen(demo) ; 
demo.setVisible(true); 


些 代码 后 ， 运 行 代码 ， 将 会 显示 如 6.2 图 的 界面 。 


6.3 ChartFactory ž 


在 上 面 的 实例 代码 中 ， 我 们 使 用 ChartFactory 类 来 组 装 一 个 JFreeChart 实 例 来 显示 
一 个 直方 条 形 图 。 下 面 我 们 更 仔细 的 看 一 下 该 类 是 如 何 工 作 的 ， 因 此 我 们 可 以 看 到 
直方 条 形 图 更 多 底层 的 框架 结构 。 理 解 底层 结构 的 关键 是 能 定制 图 表 的 外 观 。 下 面 
是 ChartFactory 方 法 createBarChart() 方 法 部 分 代码 : 


CategoryAxis categoryAxis = new CategoryAxis(categoryAxisLabel) ; 
ValueAxis valueAxis = new NumberAxis(valueAxisLabel); 
BarRenderer renderer = new BarRenderer(); 


CategoryPlot plot = new CategoryPlot(dataset, categoryAxis, valu 
eAxis, 

renderer); 

plot.setOrientation(orientation); 

JFreeChart chart = new JFreeChart(title, JFreeChart .DEFAULT_TITL 
E FONT, plot, legend); 


以 下 就 是 代码 所 做 的 工作 。 


e 我 们 的 直方 条 形 图 有 两 个 轴 ， 一 个 轴 显 示 dataset (CategoryAxis) 的 种 类 ， 另 
一 个 是 显示 带 有 数据 (NumberAxis) 刻度 的 数据 轴 。 上 面 代码 中 代码 1、2 行 
建立 了 这 两 个 轴 ， 轴 的 标签 是 createBarChart() 方 法 传 入 的 。 

。 第 三 行 ， 创 建 了 一 个 BarRender 一 一 该 类 为 每 一 个 数据 项 目 画 直方 图 。 访 
render 处 理 大 部 分 画图 工作 ， 我 们 后 续 代码 也 会 看 到 可 以 使 用 另 一 个 类 型 的 
render 替 换 现 有 的 render， 来 改变 图 表 的 整个 外 观 。 

e Dataset、axes 和 render 都 由 CategorryPlot 来 管理 ，CategorryPlot 系 统 组 件 之 
间 的 大 部 分 交互 工作 。 当 我 们 定制 一 个 图 表 时 ， 我 们 经 常 需要 先 获得 整个 图 表 
plot、renderer 和 dataset 的 引用 。 在 代码 的 第 四 行 ， 创 建 了 一 个 plot， 然 后 其 他 
组 件 对 它 进 行 赋值 。 

e 最 后 ， 在 JFreeChart 实 例 中 ， 这 个 plot 用 指定 的 标题 被 封装 。JFreeChart 类 提 
供 了 比较 高 层次 的 访问 图 表 。 但 在 这 个 plot 曾 思 图 表 就 大 部 分 被 定义 出 来 了 

(Plot 管 理 很 多 对 象 ， 例 如 axes、dataset 和 renderer) ° 





更 多 的 定制 我 们 图 表 的 方法 。 


6.4 直方 条 形 图 的 简单 定制 


调用 JFreeChart 和 CategoryPlot 类 方法 可 以 进行 一 些 简 单 的 直方 图 表 外 观 的 修改 。 
例如 ， 改 变 图表 和 区 域 的 背景 颜色 代码 如 下 : 


chart.setBackgroundPaint (Color.white) ; 

CategoryPlot plot = (CategoryPlot) chart.getPlot(); 
plot.setBackgroundPaint(Color.lightGray); 

plot .setRangeGridlinePaint(Color.white); 


该 片段 代码 (摘自 BarExample2.java 类 ) 显示 了 改变 图 表 的 背景 颜色、 获得 图 表 的 
plot (区 域 ) 的 引用 ， 并 且 进 行 了 修改 一 一 效果 如 图 6.3. 





= Bar Demo 1 


Bar Chart Demo 





Column 1 Column 2 Column3 


Category 
MRow1 MRow 2 


图 6.3 一 个 直方 条 形 图 (参考 : BarExample2.java) 


区 域 Plot 的 引用 (CategoryPlot) 是 必须 的 一 一 转换 类 型 也 是 非常 安全 的 ， 因 为 我 
们 知道 该 图 表 类 型 使 用 CategoryPlot。JFreeChart 使 用 不 同 的 区 域 类 型 (比如 
PiePlot、XYPlot) 控制 不 同类 型 的 图 表 。 我 们 必须 将 plot 的 引用 转化 成 图 表 响 应 的 
类 型 ， 因 为 基本 类 Plot 仅 仅 定义 了 一 些 通 用 的 属性 和 方法 。 随 着 对 JFreeChart 了 解 
的 加 深 ， 我 们 将 学 习 每 一 种 图 表 使 用 的 不 同 的 plot 子 类 。 


在 我 们 的 例子 中 ， 我 们 使 用 plot 的 引用 来 改变 水 平 轴 的 网 格 线 颜 色 。 看 一 下 
CategoryPlot 类 的 API 文 件 ， 就 会 看 到 我 们 能 够 修改 的 地 方 。 





6.5 定制 外 观 


回顾 6.3 节 内 容 ，CategoryPlot 管 理 这 一 个 BarRenderer 的 实例 renderer。 如 果 我 们 
想 获 得 这 个 renderer 的 引用 ， 大 量 的 定制 选择 项 会 变 得 有 效 。 


6.5.1 a7 AY ARE 
改变 图 表 中 每 个 系列 直方 图 的 颜色 ， 使 用 如 下 代码 : 


BarRenderer renderer = (BarRenderer) plot.getRenderer(); 
renderer.setSeriesPaint(0, Color.gray); 
renderer.setSeriesPaint(1, Color.orange); 
renderer.setDrawBarOutline(false) ; 


运行 上 面 代码 显示 的 结果 如 下 图 6.4. 注 意 setSeriesPaint () 方法 是 在 抽象 
AbstractRenderer 基 类 里 面 定义 的 所 以 ， 我 们 可 以 在 任何 类 型 的 renderer 里 面 
使 用 。 





BAA 
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图 6.4 一 个 直方 条 形 图 (参考 : BarExample3 java) 





此 外 ，renderer 还 可 以 控制 每 个 种 类 中 直方 条 形 图 之 间 的 间距 。 因 此 我 们 可 以 在 同 
一 个 种 类 中 将 空间 完全 去 掉 ， 代 码 如 下 : 


BarRenderer renderer = (BarRenderer) plot.getRenderer(); 
renderer.setItemMargin(0.0); 


6.5 定制 外 观 


代码 显示 的 结果 如 图 6.5 所 示 。 


= Bar Demo 1 Sele 
Bar Chart Demo 


Column 1 Column 2 Column3 


Category 
E Row1 E Row2 


图 6.5 一 个 直方 条 形 图 (参考 : BarExample4 java ) 


注意 条 形 图 看 上 去 有 点 变 宽 主要 是 因为 JFreeChart 分 配 空间 时 ， 分 配给 种 类 条 
形 图 之 间 的 间距 的 尺度 比较 少 ， 所 以 看 上 去 就 显得 有 点 长 帘 了 。 
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6.6 示例 代码 解读 


6.6.1 体会 
与 饼 图 的 数据 集 不 同 之 处 在 于 


人 饼 图 数据 集 是 key/value 二 维 数据 〈PieDataset) 。 而 直方 条 形 图 需要 三 维 数据 
(CategoryDataset) 。 


6.6.2 类 BarChartDemo1.java 
功能 
一 个 简单 的 直方 条 形 图 。 使 用 GradientPaint 实 例 对 象 为 每 一 个 系列 修改 renderer 


Bar Chart Demo 1 





4° 
eh 


Che 
ae 
Ne ca 


N° 
oe 
ne cA 


N? 
ao 
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ce 


Category 


@ First @ Second @ Third 





代码 : 


public class BarChartDemo1 extends ApplicationFrame { 
private static final long serialVersionUID = 1L; 
public BarChartDemo1i(String string) { 
super(string); 
JPanel jpanel = createDemoPanel(); 
jpanel.setPreferredSize(new Dimension(500, 270)); 
setContentPane(jpanel); 


} 

private static CategoryDataset createDataset() { 
String string = "First"; 
String string 0 = "Second"; 
String string _1_ = "Third"; 


String string 2 = "Category 1"; 


String string_3_ 
String string 4_ 
String string_5_ 
String string 6_ 
DefaultCategoryDataset 


ultCategoryDataset(); 


} 


defaultcategorydataset 
defaultcategorydataset 
defaultcategorydataset 
defaultcategorydataset 
defaultcategorydataset 
defaultcategorydataset 
defaultcategorydataset 
defaultcategorydataset 
defaultcategorydataset 
defaultcategorydataset 
defaultcategorydataset 
defaultcategorydataset 
defaultcategorydataset 
defaultcategorydataset 


defaultcategorydataset 


"Category 2"; 
"Category 3"; 
"Category 4"; 
"Category 5"; 
defaultcategorydataset 
.addValue(1. 
.addValue(4. 
.addValue(3. 
.addValue(5. 
.addValue(5. 
.addValue(5. 
.addValue(7. 
.addValue(6. 
.addValue(8. 
.addValue(4. 
.addValue(4. 
.addValue(3. 
.addValue(2. 
.addValue(3. 


.addValue(6. 


return defaultcategorydataset; 


9 
9 
0, 
O, 
9 
9 


String， 
String， 
string, 
string, 
string, 
string_0_, 
string_0_, 
string_0_, 
string_0_, 
String_ 0_， 
String_ 1 ， 
string_1_, 
string_1_, 


string_1_, 


string_1_, 


string_ 
string_6_ 


new Defa 


a a w n 


—); 
—); 
—); 
—); 
); 
string_2 
string_3 
string_4 
string_5 
string_6 
string_2 
string_3 
string_4 
string_5 


string_6 


private static JFreeChart createChart(CategoryDataset catego 
rydataset) { 


JFreeChart jfreechart 


Chart Demo i", 


"Category", 


n.VERTICAL, 


tPlot(); 


true, true, 


"Value", 


false); 


= ChartFactory.createBarChart ("Bar 


了 


categorydataset, 


jfreechart.setBackgroundPaint (Color .WHITE) ; 


CategoryPlot categoryplot = 


categoryplot. 
categoryplot. 
categoryplot. 
categoryplot. 
/ /刻度 轴 刻度 设置 

NumberAxis numberaxis 


geAxis(); 
numberaxis.setStandardTickUnits(NumberAxis.createInteger 
TickUnits()); 


//rendererik £ 


PlotOrientatio 


(CategoryPlot) jfreechart.ge 


setBackgroundPaint(Color.lightGray); 
setDomainGridlinePaint(Color.white); 
setDomainGridlinesVisible(true); 
setRangeGridlinePaint(Color.white); 


= (NumberAxis) categoryplot.getRan 


BarRenderer barrenderer = (BarRenderer) categoryplot.get 


Renderer(); 


barrenderer.setDrawBarOutline(false) ;//7% E IVR AAT 
GradientPaint gradientpaint = new GradientPaint(0.OF, 0. 


OF, Color.blue, 


0.0F, 


0.0F, 


tions 


} 


0.0F, 0O.0F, new Color(0, 0, 64)); 


GradientPaint gradientpaint_7_ = new GradientPaint(0.0F, 
Color.green, 0.0F, 0.0F, new Color(0, 64, 0)); 
GradientPaint gradientpaint_8_ = new GradientPaint(0.0F, 


Color.red, 0.0F, 0.0F, new Color(64, ©, 0)); 
barrenderer.setSeriesPaint(0, gradientpaint); 
barrenderer.setSeriesPaint(1, gradientpaint_7_); 
barrenderer.setSeriesPaint(2, gradientpaint_8_); 

// 设 置 种 类 标签 旋转 的 角度 ， 逆 时 针 旋 转 
CategoryAxis categoryaxis = categoryplot.getDomainAxis() 


categoryaxis.setCategoryLabelPositions(CategoryLabelPosi 


.createUpRotationLabelPositions(Math.PI / 6)); 
return jfreechart; 


public static JPanel createDemoPanel() { 


} 


JFreeChart jfreechart = createChart(createDataset()); 
return new ChartPanel(jfreechart); 


public static void main(String[] strings) { 


BarChartDemo1 barchartdemo1 = new BarChartDemo1("Bar Cha 


rt Demo"); 


barchartdemo1.pack(); 
RefineryUtilities.centerFrameOnScreen(barchartdemot ); 
barchartdemo1.setVisible(true); 


组 序 代码 说 明 : 


Main() 方法 执行 直方 条 形 图 。 编 写 方法 与 饼 图 一 样 。 
BarChartDemol 构造 函数 中 创 了 一 个 JPanel， 并 设置 大 小 。 
createDemoPanel() 方法 创建 了 一 个 JPanel， 并 且 在 该 panel| 上 创建 了 直方 


条 形 图 。 


createDataset() 方法 创建 了 数据 集 。 类 型 为 CategoryDataset。 注 意 数据 


集 为 三 维 数据 。 与 饼 图 不 同 。 


Ë © 


categoryplot.setBackgroundPaint(Color.lightGray) : 设置 直方 条 形 


使 用 chartFactory.createBarchart() 方法 创建 直方 条 条 形 图 
jfreechart.setBackgroundPaint(Color.WHITE) : 设置 图 表 的 背景 闫 


2 


图 的 背景 颜色 。 


setDomainGridlinePaint (Color.whites) :设置 重 直 格 线 的 颜色 。 默 认 





6.6 示例 代码 解读 


不 可 见 。 
e setRangeGridlinePaint(Color.white) : 设置 水 平 格 线 的 颜色 。 默 认可 
je 


° Bh ERE a OSES : 设 
置 数据 轴 的 刻度 递 进 范围 。 
GradientPaint 类 用 来 设置 渐变 色 。 
categoryaxis.setCategoryLabelPositions() :设置 标签 文字 旋转 的 角 
度 。 


6.6.3 类 BarChartDemo2.java 
功能 
显示 水 平 的 直方 条 形 图 。 


= Bar Chart Demo 2 TBR) 
Bar Chart Demo 2 


Factor 1 
Factor 2 
Factor 3 
Factor 4 
Factor 5 
Factor 6 
Factor 7 


Factor 8 
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代码 : 


=i 
N 
Cn 


private static CategoryDataset createDataset() { 

double[][] ds = { { 1.0, 43.0, 35.0, 58.0, 54.0, 77.0, 71.0, 
89.0 }, 

{ 54.0, 75.0, 63.0, 83.0, 43.0, 46.0, 27.0, 13.0 }, 

{ 41.0, 33.0, 22.0, 34.0, 62.0, 32.0, 42.0, 34.0 } }; 

return DatasetUtilities.createCategoryDataset("Series ", "Fa 
elon. ds 已 
} 
private static JFreeChart createChart(CategoryDataset categoryda 
taset) { 

JFreeChart jfreechart = ChartFactory.createBarChart("Bar Cha 
rt Demo 2", 

"Category", "Score (%)", categorydataset, 
PlotOrientation.VERTICAL, true, true, false); 
jfreechart.setBackgroundPaint(Color.white); 

CategoryPlot categoryplot = (CategoryPlot) jfreechart.getPlo 
t(); 

categoryplot.setBackgroundPaint(Color.lightGray); 

categoryplot.setRangeGridlinePaint(Color.white); 

categoryplot.setRangeAxisLocation(AxisLocation.BOTTOM_OR_LEF 
T); 

NumberAxis numberaxis = (NumberAxis) categoryplot.getRangeAx 
is(); 

numberaxis.setRange(0.0, 100.0); 

numberaxis.setStandardTickUnits(NumberAxis.createIntegerTick 


Units()); 
BarRenderer barrenderer = (BarRenderer) categoryplot.getRend 
erer(); 
barrenderer.setDrawBarOutline( false); 
barrenderer 
.setLegendItemToolTipGenerator(new StandardCategorySerie 
sLabelGenerator ( 


"Tooltip: {0}")); 
return jfreechart; 


程序 代码 说 明 : 
o 数据 集 的 创建 另 一 种 方式 ， 使 用 二 维 数 组 。 


7 折线 图 


7.1 简介 


本 章 讲述 了 JFreeChart 创 建 折线 图 的 内 容 。 我 们 可 以 使 用 CategoryDataset 或 
XYDataset 数 据 集 接 口 创 建 折线 图 。 


7.2 使 用 categoryDataset 数 据 集 创建 折线 图 


7.2.1 概述 


使 用 CategoryDataset 创 建 的 折线 图 将 每 个 数据 点 〈 种 类 ， 值 ) 使 用 一 条 直线 连接 
起 来 。 本 章 讲 的 一 个 简单 应 用 产生 如 下 界面 ， 如 图 7.1 : 


2 JFreeChart — Line Chart Demo 1 
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JDK 1.0 JDK 1.1 JDK 1.2 JDK 1.3 JDK 1.4 JDK 1.5 





Source: Java In A Nutshell (Sth Edition) by David Flanagan (O'Reilly) 
图 7.1 一 个 简单 的 折线 图 
全 部 的 代码 简 JFreeChart 开 发 指南 一 并 下 载 的 demo (参考 : 


LineChartDemo1.java) ° 


7.2.2 CategoryDataset 


正如 其 他 图 表 一 样 ， 创 建 折线 图 的 第 一 步 是 创建 第 一 个 dataset。 在 本 例子 中 ， 使 用 
DefaultCategoryDataset， 代 码 如 下 : 


private static CategoryDataset createDataset() { 
DefaultCategoryDataset defaultcategorydataset = new DefaultC 


ategoryDataset(); 
defaultcategorydataset.addValue(212.0, 


defaultcategorydataset.addValue(504.0, 
defaultcategorydataset .addValue(1520.0, 
defaultcategorydataset .addValue(1842.0, 
defaultcategorydataset .addValue(2991.0, 
defaultcategorydataset .addValue(3500.0, 


return defaultcategorydataset; 


注意 : 你 可 以 使 用 任何 实现 Category 接 口 的 数据 集 。 


7.2.3 创建 图 表 


"Classes", "JDK 1.0") 
"Classes", "JDK 1.1") 
"Classes", "JDK 1.2" 
"Classes", "JDK 1.3" 
"Classes", "JDK 1.4" 


"Classes", "JDK 1.5" 


ChartFactory 类 提供 了 一 个 便利 的 方法 createLineChart() 创 建 折线 图 。 代 码 如 下 


JFreeChart jfreechart = ChartFactory.createLineChart( 
"Java Standard Class Library",// 图 表 标 题 


null, // 主轴 标签 
"Class Count",// 范围 轴 标 签 
categorydataset, // 数据 集 
PlotOrientation.VERTICAL,// 方向 
false, // 是 否 
true, // 提示 信息 是 否 显示 
false// 25k Murls 

); 


该 方法 构建 了 一 个 带 有 标题 、 、 和 相应 的 数 轴 和 心态 提示 产生 器 的 JFreeChart 


对 象 。 创 建 Dataset 数 据 集 的 过 程 见 上 节 。 


7.2.4 定制 图 表 


折线 图 表 将 使 用 大 部 分 缺 省 的 属性 来 进行 初始 化 。 妆 然 了 ， 我 们 也 可 以 随意 修改 折 


线 图 的 属性 ， 来 改变 我 们 图 表 的 外 观 。 在 本 例 中 ， ， 我们 通 
图 : 


e@ 在 图 表 上 添加 两 个 副标题 
e@ 图 表 的 背景 磊 色 设 成 白色 ; 
o 图 区 背景 颜色 设 成 亮 灰 色 ; 
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过 下 面 的 方式 定制 折线 


° Piian 色 改 变 成 白色 ; 
o 范围 轴 修 改 成 仅 显 示 整 数 数值 ; 
° renderer T 白色 卉 充 的 形状 。 


首先 ， 将 副标题 添加 在 缺 省 的 位 置 ( 主 标题 下 方 ) ， 代 码 如 下 


jfreechart.addSubtitle(new TextTitle("Number of Classes By Relea 
se")); 


第 二 TEEMA TAARN R 来 改变 字体 ， 并 放置 在 图 表 的 下 方 ， 并 且 靠 
右 对 其 ， 代 码 如 下 


TextTitle texttitle = (new TextTitle("Source: Java In A Nutshell 
(5th Edition) by David Flanagan (O'Reilly)")); 
texttitle.setFont(new Font("SansSerif", ©, 10)); 
texttitle.setPosition(RectangleEdge.BOTTOM) ; 
texttitle.setHorizontalAlignment (HorizontalAlignment.RIGHT); 
jfreechart.addSubtitle(texttitle); 


改变 图 表 的 背景 颜色 非常 简单 ， 因 为 JFreeChart 类 就 有 设置 背景 颜色 的 属性 。 代 码 
如 下 : 


// 改 变 图 表 的 背景 颜色 
jfreechart.setBackgroundPaint(Color.white); 


en aris 性 的 ， 则 需要 首先 获得 图 表 CategoryPlot 对 象 的 引用 ， 然 后 对 该 引 
进行 相应 属性 的 设置 。 获 得 对 象 引 用 的 代码 如 下 


CategoryPlot categoryplot = (CategoryPlot) jfreechart.getPlot(); 


使 用 CategoryPlot 设 置 图 区 的 背景 颜色 为 亮 灰 色 ， 设 置 网 格 线 颜 色 为 白色 的 代码 如 
下 


categoryplot.setBackgroundPaint(Color.lightGray) ) ; 
categoryplot.setRangeGridlinePaint(Color.white); 


图 区 负责 在 图 表 上 画 出 数据 和 轴 。 其 中 一 部 分 工作 由 renderer 来 完成 ， 我 们 可 以 通 
过 getRender() 来 获得 = renderer’ o renderer 维 护 大 部 分 与 图 表 内 数据 项 的 显示 相 
关 的 属性 。 代 码 如 下 


LineAndShapeRenderer renderer = (LineAndShapeRenderer) categoryp 
lot .getRenderer(); 

renderer .setShapesVisible(true); 

renderer.setDrawOutlines(true); 

renderer .setUseFillPaint(true); 


同时 图 区 也 管理 着 图 表 所 有 的 轴 。 在 本 实例 中 ， 修 改 范围 轴 以 便 范 围 轴 的 刻度 标签 
显示 为 整数 值 。 


NumberAxis rangeAxis = (NumberAxis) categoryplot.getRangeAxis(); 
rangeAxis.setStandardTickUnits(NumberAxis.createIntegerTickUnits 


()); 


定制 图 表 还 有 很 多 其 他 的 方式 。 具 体 的 内 容 详 见 本 文档 相关 章节 ，API 文 档 以 及 源 
代码 实例 。 


7.2.5 程序 的 全 部 代码 


Rony EE AN Lene Leen 
* LineChartDemo1.java 


* 


* (C) Copyright 2002-2005, by Object Refinery Limited. 
* 


=y 

package demo; 

import java.awt.BasicStroke; 

import java.awt.Color; 

import java.awt.Dimension; 

import java.awt.Font; 

import java.awt.geom.Ellipse2D; 

import java.net.URL; 

import javax.swing.īImageIcon; 

import javax.swing.JPanel; 

import org.jfree.chart.ChartFactory; 

import org.jfree.chart.ChartPanel; 

import org.jfree.chart.JFreeChart; 

import org.jfree.chart.axis.NumberAxis; 

import org.jfree.chart.plot.CategoryPlot; 

import org.jfree.chart.plot.PlotOrientation; 

import org.jfree.chart.renderer.category.LineAndShapeRenderer ; 
import org.jfree.chart.title.TextTitle; 

import org.jfree.data.category.CategoryDataset; 

import org.jfree.data.category.DefaultCategoryDataset; 
import org.jfree.ui.ApplicationFrame; 

import org.jfree.ui.HorizontalAlignment; 

import org.jfree.ui.RectangleEdge; 

import org.jfree.ui.RefineryUtilities; 

public class LineChartDemo1 extends ApplicationFrame { 


[ise 
大 


EA 
private static final long serialVersionUID = -63543506043130 
79793L; 
/* synthetic */static Class class$demo$LineChartDemo1; 
public LineChartDemo1i(String string) { 
super(string); 
JPanel jpanel = createDemoPanel(); 
jpanel.setPreferredSize(new Dimension(500, 270)); 
setContentPane(jpanel); 
} 
private static CategoryDataset createDataset() { 
DefaultCategoryDataset defaultcategorydataset = new Defa 
ultCategoryDataset(); 
defaultcategorydataset.addValue(212.0, "Classes", "JDK 1 


SAS 

defaultcategorydataset.addValue(504.0, "Classes", "JDK 1 
I; 

defaultcategorydataset.addValue(1520.0, "Classes", "JDK 
1.2"); 

defaultcategorydataset.addValue(1842.0, "Classes", "JDK 
1.3"); 

defaultcategorydataset.addValue(2991.0, "Classes", "JDK 
bea 

defaultcategorydataset.addValue(3500.0, "Classes", "JDK 
1.5"); 

return defaultcategorydataset; 

} 


private static JFreeChart createChart(CategoryDataset catego 
rydataset) { 
JFreeChart jfreechart = ChartFactory.createLineChart( 
"Java Standard Class Library",// 图 表 标 题 
null, // 主轴 标签 
"Class Count",// 范围 轴 标 签 
categorydataset, // 数据 集 
PlotOrientation.VERTICAL,// 方向 
false, // 是 否 包含 图 例 
true, // 提示 信息 是 否 显示 
false// 是 否 使 用 urls 
); 
// 添加 主 标题 
jfreechart.addSubtitle(new TextTitle("Number of Classes 
By Release")); 
TextTitle texttitle = (new TextTitle( 
"Source: Java In A Nutshell (5th Edition) by David F 
lanagan (0O'Reilly)")); 
texttitle.setFont(new Font("SansSerif", ©, 10)); 
texttitle.setPosition(RectangleEdge.BOTTOM) ; 
texttitle.setHorizontalAlignment (HorizontalAlignment.RIG 
HT); 
jfreechart.addSubtitle(texttitle); 
// 改变 图 表 的 背景 颜色 


jfreechart.setBackgroundPaint(Color.white); 

CategoryPlot categoryplot = (CategoryPlot) jfreechart.ge 
tPlot(); 

categoryplot.setBackgroundPaint(Color.lightGray) ; 

categoryplot.setRangeGridlinePaint(Color.white) ; 

categoryplot.setRangeGridlinesVisible( false); 

URL url = (class$demo$LineChartDemoi == null ? class$dem 
o$LineChartDemo1 = class$("demo.LineChartDemo1" ) 

class$demo$LineChartDemo1) .getClassLoader().getRes 


ource( 
"OnBridgeiismall.png"); 
if (url != null) { 
ImageIcon imageicon = new ImagelIcon(url); 
jfreechart.setBackgroundImage(imageicon.getImage()); 
categoryplot.setBackgroundPaint(new Color(0, 0, 0, © 
) ) ; 
} 
NumberAxis numberaxis = (NumberAxis) categoryplot.getRan 
geAxis(); 


numberaxis.setStandardTickUnits(NumberAxis.createInteger 
TickUnits()); 
LineAndShapeRenderer lineandshaperenderer = (LineAndShap 
eRenderer) categoryplot 
.getRenderer(); 
lineandshaperenderer .setShapesVisible(true); 
lineandshaperenderer.setDrawOutlines(true); 
lineandshaperenderer.setUseFillPaint(true); 
lineandshaperenderer .setBaseFillPaint(Color.white); 
lineandshaperenderer .setSeriesStroke(0, new BasicStroke( 
3.0F)); 
lineandshaperenderer.setSeriesOutlineStroke(0, new Basic 
Stroke(2.0F)); 
lineandshaperenderer.setSeriesShape(0, new Ellipse2D.Dou 
ble(-5.0, -5.0, 
10.0, 10.0)); 
LineAndShapeRenderer renderer = (LineAndShapeRenderer) c 
ategoryplot 
.getRenderer(); 
renderer.setShapesVisible(true); 
renderer .setDrawOutlines(true); 
renderer.setUseFillPaint(true); 
return jfreechart; 
} 
public static JPanel createDemoPanel() { 
JFreeChart jfreechart = createChart(createDataset()); 
return new ChartPanel(jfreechart); 
} 
public static void main(String[] strings) { 
LineChartDemo1 linechartdemo1 = new LineChartDemo1( 
"JFreeChart - Line Chart Demo 1"); 
linechartdemo1.pack(); 
RefineryUtilities.centerFrameOnScreen(linechartdemot) ; 
linechartdemo1.setVisible(true); 


} 
/* synthetic */ 
static Class class$(String string) { 
Class var_class; 
try { 
var_class = Class.forName(string); 
} catch (ClassNotFoundException classnotfoundexception) 


{ 
throw new NoClassDefFoundError(classnotfoundexceptio 
n.getMessage()); 


return var_class; 


7.3 使 用 XYDataset 数 据 集 创建 折线 图 


7.3.1 概述 


折线 图 也 可 以 使 用 XYDataset 数 据 集 ， 使 用 一 条 直线 将 相 邻 的 点 (X，y) 点 连接 起 
来 。 本 章 介 绍 的 一 个 使 用 XYDataset 数 据 集 创 建 折 线 图 的 简单 实例 ， 如 下 图 7.2 所 
示 fo} 
= Line Chart Demo 2 TBR) 
Line Chart Demo 2 
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图 7.2 一 个 简单 的 基于 XYDataset 数 据 集 的 折线 图 (参考 : LineChartDemo2.java) 





7.3.2 XYDataset 


对 于 该 图 表 来 说 ， 使 用 的 数据 集 是 XYSeriesCollection (当然 我 们 可 以 使 用 实现 
XYDataset 接 口 的 其 他 数据 集 ) 。 出 于 独立 演示 的 目 点 ， 我 们 创建 的 dataset 代 码 如 
下 


private static XYDataset createDataset() { 
XYSeries xyseries = new XYSeries("First"); 
xyseries.add(1.0, 1.0); 


xyseries.add(2.0, 4.0); 
xyseries.add(3.0, 3.0); 
xyseries.add(4.0, 5.0); 
xyseries.add(5.0, 5.0); 
xyseries.add(6.0, 7.0); 
xyseries.add(7.0, 7.0); 


xyseries.add(8.0, 8.0); 
XYSeries xyseries © = new XYSeries("Second"); 
xyseries_0_.add(1.0, 5.0); 
xyseries_0_.add(2.0, 7.0); 
xyseries_0_.add(3.0, 6.0); 
xyseries_ 0 .add(4.0, 8.0); 
xyseries_0_.add(5.0, 4.0); 
xyseries_0_.add(6.0, 4.0); 
xyseries 0 _.add(7.0, 2.0); 
xyseries_0_.add(8.0, 1.0); 
XYSeries xyseries 1 = new XYSeries("Third"); 
xyseries 1 .add(3.0, 4.0); 
xyseries 1 .add(4.0, 3.0); 
xyseries 1 .add(5.0, 2.0); 
xyseries 1 .add(6.0, 3.0); 
xyseries 1 .add(7.0, 6.0); 
xyseries 1 .add(8.0, 3.0); 
xyseries 1 .add(9.0, 4.0); 
xyseries 1 .add(10.0, 3.0); 
XYSeriesCollection xyseriescollection = new XYSeriesCollecti 
on(); 
xyseriescollection.addSeries(xyseries); 
xyseriescollection.addSeries(xyseries_0_); 
xyseriescollection.addSeries(xyseries_ 1 ); 
return xyseriescollection; 


注意 : 每 个 系列 必须 有 X 值 (不 是 必须 有 y 值 ) ， 并 且 该 系列 独立 于 其 他 系列 。 数 据 
集 可 以 接受 一 个 y 值 为 null 的 值 。 当 图 表 遇 到 null 值 时 ， 连 接线 不 被 画 出 ， 该 系列 的 
连 线 不 会 连续 。 出 现下 图 7.3 类 型 。 


= Line Chart Demo 2 
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图 7.3 有 一 个 y 值 为 null 时 ， 图 表 显 示 断 续 。 


7.3.3 创建 图 表 


ChartFactory 类 提供 了 一 个 便利 的 方法 createXYLineChart() 创 图 表 : 


JFreeChart jfreechart = ChartFactory.createxYLineChart ( 
"Line Chart Demo 2", // chart title 
"X", // x axis label 
"Y", // y axis label 
xydataset, // data 
PlotOrientation.VERTICAL, 
true, // include legend 
true, // tooltips 
false // urls 


); 


上 面 方 法 构建 了 一 个 JFreeChart 对 象 ， 该 对 象 具有 一 个 标题 、 图 例 和 相关 轴 的 图 区 
及 renderer。 数 据 集 使 用 上 节 我 们 创建 的 数据 集 。 


7.3.4 定制 图 表 


图 表 将 使 用 大 部 分 缺 省 的 属性 进行 初始 化 设置 。 当 然 了 ， 我 们 也 可 以 随意 修改 这 些 
属性 ， 来 改变 我 们 图 表 的 外 观 。 在 本 实例 中 ， 设 置 的 几 个 属性 如 下 : 


设置 图 表 的 背景 颜色 

设置 图 区 的 背景 颜色 

设置 轴 的 平移 值 

设置 主轴 和 范围 轴 网 格 线 颜 色 

修改 renderer 改 变 连 线 点 的 形状 
范围 轴 刻 度 的 设置 ， 以 便 显 示 整 数值 。 


变 图 表 背 景 颜色 非常 简单 。 代 码 如 下 


// 改 变 图 表 的 背景 颜色 
jfreechart.setBackgroundPaint(Color.white); 


改变 图 区 背景 颜色 、 轴 平移 、 网 格 线 颜 色 ， 需 要 使 用 plot 图 区 对 象 的 一 个 引用 来 修 
改 。 图 片 对 象 需 要 转化 成 XYPlot 对 象 ， 主 要 是 因为 我 们 可 以 访问 更 多 更 具体 的 图 区 
方法 。 代 码 如 下 


XYPlot xyplot = (XYPlot) jfreechart.getPlot(); 
xyplot.setBackgroundPaint(Color.lightGray); 
xyplot.setAxisOffset(new RectangleInsets(5.0, 5.0, 5.0, 5.0)); 
xyplot.setDomainGridlinePaint(Color.white) ; 
xyplot.setRangeGridlinePaint(Color.white); 


修改 renderer 来 显示 连 线 之 间 的 形状 。 代 码 如 下 


XYLineAndShapeRenderer xylineandshaperenderer = (XYLineAndShapeR 
enderer) xyplot.getRenderer(); 
xylineandshaperenderer.setShapesVisible(true); 
xylineandshaperenderer.setShapesFilled(true); 


Ta RR NS PI 围 轴 。 我 们 将 默认 刻度 值 (允许 显示 小 数 ) 改 成 只 显示 整数 的 刻度 
值 。 代 码 如 下 


NumberAxis numberaxis = (NumberAxis) xyplot.getRangeAxis(); 
numberaxis.setStandardTickUnits(NumberAxis.createIntegerTickUnit 


S()); 


参考 源 代码 、Javadoc 的 API 文 档 以 及 其 他 相关 XYPlot 的 定制 内 容 ， 来 学 习 更 多 的 细 
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8 时 友 图 


8.1 简介 


时 序 图 类 似 于 折线 图 ， 唯 一 不 同 的 地 方 是 时 序 图 的 主轴 是 日 期 而 不 是 数值 。 本 章 讲 
述 如 何 使 用 JFreeChart 创 建 时 序 图 。 


8.2 创建 时 序 图 


8.2.1 概述 


时 序 图 表 的 确 是 一 个 使 用 XYDataset 数 据 集 的 折线 图 。 不 同 点 就 是 再 主轴 上 X 轴 值 
显示 的 是 日 期 。 本 章 讲述 的 一 个 简单 应 用 如 下 图 8.1 所 示 
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图 8.1 一 个 简单 的 时 序 图 表 (参考 : TimeSeriesDemo1java) ° 


上 图 实例 代码 参见 类 TimeSeriesDemo1.java。 


8.2.2 日 期 还 是 数字 ? 


创建 序 图 使 用 的 数据 集 是 XYDataset。 接 口 不 能 有 返回 日 期 类 型 以 外 的 方法 。 那 么 
JFreeChart 是 如 何 创 建 时 序 图 表 的 呢 ? 


数据 集 返 回 的 X 值 是 基本 的 double 类 型 ， 但 这 个 值 通 过 一 种 特殊 的 方式 来 进行 转译 
成 日 期 该 数 是 反映 了 一 个 从 1970/1/1 起 计算 的 一 个 毫秒 级 值 ( 译 码 过 程 使 用 
java.util.Data 类 计算 ) 。 


具体 的 轴 类 (DateAxis) 将 毫秒 级 数据 转化 成 日 期 ， 并 作为 需要 返回 该 值 ， 将 数值 
作为 主轴 刻度 显示 出 来 。 





8.2.3 数据 集 


演示 的 本 实例 ， 数 据 使 用 的 是 一 个 TimeSeriesCollection 对 象 〈 我 们 可 以 是 任何 
XYDataset 接 口 的 实现 ) 。 人 代码 如 下 : 


private static XYDataset createDataset() { 
TimeSeries timeseries = new TimeSeries( 


"L&G European Index Trust", 
(class$org$jfree$data$time$Month == null ? (class$org$jf 
ree$data$time$Month = class$("org.jfree.data.time.Month") ) 
class$org$jfree$data$time$Month) ); 
timeseries.add(new Month(2, 2001), 181.8); 
timeseries.add(new Month(3, 2001), 167.3); 
timeseries.add(new Month(4, 2001), 153.8); 
timeseries.add(new Month(5, 2001), 167.6); 
timeseries.add(new Month(6, 2001), 158.8); 
timeseries.add(new Month(7, 2001), 148.3); 
timeseries.add(new Month(8, 2001), 153.9); 
timeseries.add(new Month(9, 2001), 142.7); 
timeseries.add(new Month(10, 2001), 123.2); 
timeseries.add(new Month(11, 2001), 131.8); 
timeseries.add(new Month(12, 2001), 139.6) 
timeseries.add(new Month(1, 2002), 142.9); 
timeseries.add(new Month(2, 2002), 138.7); 
timeseries.add(new Month(3, 2002), 137.3); 
timeseries.add(new Month(4, 2002), 143.9); 
timeseries.add(new Month(5, 2002), 139.8); 
timeseries.add(new Month(6, 2002), 137.0); 
timeseries.add(new Month(7, 2002), 132.8); 
TimeSeries timeseries 0 = new TimeSeries( 
"L&G UK Index Trust", 
(class$org$jfree$data$time$Month == null ? (class$org$jf 
ree$data$time$Month = class$("org.jfree.data.time.Month") ) 
class$org$jfree$data$time$Month) ); 
timeseries 0 _.add(new Month(2, 2001), 129.6); 
timeseries 0 _.add(new Month(3, 2001), 123.2); 
timeseries 0 _.add(new Month(4, 2001), 117.2); 
timeseries 0 _.add(new Month(5, 2001), 124.1); 
timeseries 0 _.add(new Month(6, 2001), 122.6); 
timeseries 0 _.add(new Month(7, 2001), 119.2); 
timeseries 0 .add(new Month(8, 2001), 116.5); 
timeseries 0 _.add(new Month(9, 2001), 112.7); 
timeseries 0 _.add(new Month(10, 2001), 101.5); 
timeseries 0 _.add(new Month(11, 2001), 106.1); 
timeseries 0 _.add(new Month(12, 2001), 110.3); 
timeseries 0 _.add(new Month(1, 2002), 111.7); 
timeseries 0 _.add(new Month(2, 2002), 111.0); 
timeseries 0 _.add(new Month(3, 2002), 109.6); 
timeseries 0 _.add(new Month(4, 2002), 113.2); 
timeseries 0 _.add(new Month(5, 2002), 111.6); 
timeseries 0 _.add(new Month(6, 2002), 108.8); 
timeseries 0 _.add(new Month(7, 2002), 101.6); 
TimeSeriesCollection timeseriescollection = new TimeSeriesCo 
llection(); 
timeseriescollection.addSeries(timeseries); 
timeseriescollection.addSeries(timeseries_0_); 
return timeseriescollection; 


se 


实例 中 ， 系 列 包 含 了 每 月 的 数据 。 尽 管 如 此 ， 仍 然 使 用 TimeSeries 类 来 显示 间隔 的 
时 间 值 (年 ~、 日 、 


8.2.4 构建 图 表 


使 用 ChartFactory 类 提供 的 便利 方法 createTimeSeriesChart() 创 建 图 表 ， 代 码 如 
sh 


JFreeChart jfreechart = ChartFactory.createTimeSeriesChart ( 
"Legal & General Unit Trust Prices", // title 
"Date", // x-axis label 
"Price Per Unit", // y-axis label 
xydataset, // data 
true, // create legend? 
true, // generate tooltips? 
false // generate URLS? 


); 


该 方法 构建 了 一 个 带 有 标题 、 图 例 、 相 应 轴 的 区 域 和 展示 器 的 JFreeChart 对 象 。 使 
用 的 数据 集 见 上 一 节 内 容 。 


8.2.5 定制 图 表 


图 表 的 大 部 分 属性 使 用 了 缺 省 的 值 进行 初始 化 。 当 然 ， 我 们 可 以 随时 修改 这 些 属性 
的 设置 来 改变 我 们 图 表 的 外 观 展现 。 在 本 实例 中 ， 人 和 修改 的 几 个 属性 如 下 : 


e 修改 renderer， 改 变 每 个 数据 点 显示 的 系列 形状 ， 数 据点 之 间 的 折线 除外 。 
o 主轴 的 数据 格式 进行 格式 化 后 显示 。 


修改 renderer 需 要 一 下 两 个 步骤 : 获得 renderer 引 用 和 将 renderer 对 象 转 化 成 
XYLineAndShapeRenderer 类 型 。 代 码 如 下 : 


XYItemRenderer xyitemrenderer = xyplot.getRenderer(); 

if (xyitemrenderer instanceof XYLineAndShapeRenderer) { 
XYLineAndShapeRenderer xylineandshaperenderer = (XYLineAndSh 

apeRenderer) xyitemrenderer; 
xylineandshaperenderer .setBaseShapesVisible(true) ; 
xylineandshaperenderer.setBaseShapesFilled(true); 


最 后 ， 将 格式 化 的 数据 传 给 主轴 ， 以 改变 显示 。 代 码 如 下 : 


DateAxis dateaxis = (DateAxis) xyplot.getDomainAxis(); 
dateaxis.setDateFormatOverride(new SimpleDateFormat ("MMM-yyyy" )) 


£ 


当 设 置 了 Dataaxis 时 ， 系 统 将 自动 选择 一 个 DataTickUnit 来 显示 主轴 刻度 。 但 系统 
将 使 用 上 面 我 们 格式 化 的 数据 来 显示 ， 而 不 是 系统 默认 的 格式 。 


8.2.6 全 部 代码 


文档 的 全 部 代码 如 下 : 


/* TimeSeriesDemo1 - Decompiled by JODE 
* Visit http://jode.sourceforge.net/ 
a 
package demo; 
import java.awt.Color; 
import java.awt.Dimension; 
import java.text.SimpleDateFormat; 
import javax.swing.JPanel; 
import org.jfree.chart.ChartFactory; 
import org.jfree.chart.ChartPanel; 
import org.jfree.chart.JFreeChart; 
import org.jfree.chart.axis.DateAxis; 
import org.jfree.chart.plot.XYPlot; 
import org.jfree.chart.renderer.xy.XYLineAndShapeRenderer ; 
import org.jfree.data.time.Month; 
import org.jfree.data.time.TimeSeries; 
import org.jfree.data.time.TimeSeriesCollection; 
import org.jfree.data.xy.XyYDataset; 
import org.jfree.ui.ApplicationFrame; 
import org.jfree.ui.RectangleInsets; 
import org.jfree.ui.RefineryUtilities; 
public class TimeSeriesDemo1 extends ApplicationFrame { 
private static final long serialVersionUID = -54122863709566 
46368L,; 
/* synthetic */ 
static Class class$org$jfree$data$time$Month; 
public TimeSeriesDemo1i(String string) { 
super(string); 
XYDataset xydataset = createDataset(); 
JFreeChart jfreechart = createChart(xydataset); 
ChartPanel chartpanel = new ChartPanel(jfreechart, false 
); 
chartpanel.setPreferredSize(new Dimension(500, 270)); 
chartpanel.setMouseZoomable(true, false); 
setContentPane(chartpanel); 
} 
private static JFreeChart createChart(XYDataset xydataset) { 
JFreeChart jfreechart = ChartFactory.createTimeSeriesCha 
rt( 
"Legal & General Unit Trust Prices", // title 
"Date", // x-axis label 
"Price Per Unit", // y-axis label 
xydataset, // data 
true, // create legend? 


true, // generate tooltips? 
false // generate URLS? 
); 
jfreechart.setBackgroundPaint(Color.white); 
XYPlot xyplot = (XYPlot) jfreechart.getPlot(); 
xyplot.setBackgroundPaint(Color.lightGray); 
xyplot.setDomainGridlinePaint(Color.white); 
xyplot.setRangeGridlinePaint(Color.white); 
xyplot.setAxisOffset(new RectangleInsets(5.0, 5.0, 5.0, 
5.0)); 
xyplot.setDomainCrosshairVisible(true); 
xyplot.setRangeCrosshairVisible(true) ; 
org.jfree.chart.renderer.xy.XYItemRenderer xyitemrendere 
r = xyplot 
.getRenderer(); 
if (xyitemrenderer instanceof XYLineAndShapeRenderer) { 
XYLineAndShapeRenderer xylineandshaperenderer = (XYL 
ineAndShapeRenderer) xyitemrenderer; 
xylineandshaperenderer .setBaseShapesVisible(true) ; 
xylineandshaperenderer .setBaseShapesFilled(true); 
} 
DateAxis dateaxis = (DateAxis) xyplot.getDomainAxis(); 
dateaxis.setDateFormatOverride(new SimpleDateFormat ("MMM 


-yyyy")); 
return jfreechart; 
} 


private static XYDataset createDataset() { 

TimeSeries timeseries = new TimeSeries( 

"L&G European Index Trust", 

(class$org$jfree$data$time$Month == null ? (class$or 

g$jfree$data$time$Month = class$("org.jfree.data.time.Month")) 
class$org$jfree$data$time$Month)); 

timeseries.add(new Month(2, 2001), 181.8); 
timeseries.add(new Month(3, 2001), 167.3); 
timeseries.add(new Month(4, 2001), 153.8); 
timeseries.add(new Month(5, 2001), 167.6); 
timeseries.add(new Month(6, 2001), 158.8); 
timeseries.add(new Month(7, 2001), 148.3); 
timeseries.add(new Month(8, 2001), 153.9); 
timeseries.add(new Month(9, 2001), 142.7); 
timeseries.add(new Month(10, 2001), 123.2); 
timeseries.add(new Month(11, 2001), 131.8); 
timeseries.add(new Month(12, 2001), 139.6); 
timeseries.add(new Month(1, 2002), 142.9); 
timeseries.add(new Month(2, 2002), 138.7); 
timeseries.add(new Month(3, 2002), 137.3); 
timeseries.add(new Month(4, 2002), 143.9); 
timeseries.add(new Month(5, 2002), 139.8); 
timeseries.add(new Month(6, 2002), 137.0); 
timeseries.add(new Month(7, 2002), 132.8); 
TimeSeries timeseries 0 = new TimeSeries( 

"L&G UK Index Trust", 

(class$org$jfree$data$time$Month == null ? (class$or 


g$jfree$data$time$Month = class$("org.jfree.data.time.Month") ) 


class$org$jfree$data$time$Month) ); 
timeseries 0 _.add(new Month(2, 2001), 129.6); 
timeseries 0 _.add(new Month(3, 2001), 123.2); 
timeseries 0 _.add(new Month(4, 2001), 117.2); 
timeseries 0 _.add(new Month(5, 2001), 124.1); 
timeseries 0 _.add(new Month(6, 2001), 122.6); 
timeseries 0 _.add(new Month(7, 2001), 119.2); 
timeseries 0 .add(new Month(8, 2001), 116.5); 
timeseries 0 _.add(new Month(9, 2001), 112.7); 
timeseries_0_.add(new Month(10, 2001), 101.5); 
timeseries 0 _.add(new Month(11, 2001), 106.1); 
timeseries_0_.add(new Month(12, 2001), 110.3); 
timeseries 0 _.add(new Month(1, 2002), 111.7); 
timeseries 0 _.add(new Month(2, 2002), 111.0); 
timeseries 0 _.add(new Month(3, 2002), 109.6); 
timeseries 0 _.add(new Month(4, 2002), 113.2); 
timeseries 0 _.add(new Month(5, 2002), 111.6); 
timeseries 0 _.add(new Month(6, 2002), 108.8); 
timeseries 0 _.add(new Month(7, 2002), 101.6); 
TimeSeriesCollection timeseriescollection = new TimeSeri 


esCollection(); 


{ 


timeseriescollection.addSeries(timeseries); 
timeseriescollection.addSeries(timeseries 0_); 
return timeseriescollection; 

} 

public static JPanel createDemoPanel() { 
JFreeChart jfreechart = createChart(createDataset()); 
return new ChartPanel(jfreechart); 

} 

public static void main$(String[] strings) { 
TimeSeriesDemo1 timeseriesdemo1 = new TimeSeriesDemo1( 

"Time Series Demo 1"); 

timeseriesdemo1.pack(); 
RefineryUtilities.centerFrame0nScreen(timeseriesdemo1); 
timeseriesdemo1.setVisible(true); 


public static void main(String[] args) { 
main$(args); 
} 


/* synthetic */ 
static Class class$(String string) { 
Class var_class; 
try { 
var_class = Class.forName(string); 
} catch (ClassNotFoundException classnotfoundexception) 


throw new NoClassDefFoundError(classnotfoundexceptio 


n.getMessage()); 


return var_class; 


8.2 创建 时 序 图 
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9 定制 图 表 (Customising Charts ) 


9.1 简介 


JFreeChart 的 设计 的 定制 功能 是 非常 灵活 的 。 我 们 可 以 使 用 非常 多 的 属性 来 设置 我 
们 图 表 的 外 观 。 本 章 将 详细 介绍 一 些 图 表 通 用 的 定制 技术 。 


9.2 图 表 属 性 


9.2.1 概述 


我 们 可 以 使 用 JFreeChart 类 方法 从 更 高 的 层次 来 定制 我 们 图 表 的 外 观 。 可 控制 的 属 
性 有 : 

e@ 图 表 的 边框 

e 图 表 的 标题 和 副标题 

e ARYA ae 色 和 图 片 

e 使 用 绘制 建议 (Rendering Hints) 画图 表 ， 该 属性 有 是 否 反馈 齿 功能 。 


在 下 面 的 章节 中 将 详细 描述 这 些 内 容 。 


9.2.2 图 表 边 框 


JFreeChart 可 以 在 图 表 的 外 围 画 出 一 个 边框 。 默 认 状 态 下 ，JFreeChart 是 不 画 出 边 
框 的， 但 我 们 可 以 使 用 方法 setBorderVisible() 来 设 o 边框 的 颜色 和 线条 风格 可 使 
用 方法 setBorderPaint() 和 setBorderStroke() 来 控制 


注意 : 如 果 我 们 在 一 个 ChartPanel 里 面 显示 我 们 的 图 表 ， 那 么 我 们 可 能 更 愿意 使 用 
Swing 提 供 的 边框 。 


9.2.3 图 表 标 题 


图 表 有 一 个 标题 ， 显 示 在 图 表 的 顶部 、 底 部 、 左 侧 或 右 侧 (同时 ， 我 们 也 可 以 添加 
副标题 ， 见 下 章 讲 述 ) 。 标 题 使 用 一 个 TextTitle 的 实例 对 象 。 我 们 可 以 使 用 
getTitle() 方 法 来 获得 标题 的 引用 。 


TextTitle texttitle = jfreechart.getTitle(); 


修改 标题 文本 (不 修改 字体 和 位 置 ) 的 代码 如 下 


texttitle.setText("Pie Chart Demo"); 


题 头 放置 在 图 表 的 顶部 、 底 部 、 左 侧 或 右 侧 的 设置 ， 使 用 标题 本 书 属性 设置 来 完 
成 。 下 面 代码 显示 的 是 将 标题 移植 到 图 表 的 底部 。 


texttitle.setPosition(RectangleEdge.BOTTOM) ; 


如 果 在 我 们 图 表 上 ， 我 们 不 希 示 标 题 ， 则 将 标题 设置 为 null 即 可 。 


9.2.4 副标题 


图 表 可 以 拥有 任何 数量 的 副标题 。 添 加 副标题 ， 需 要 先 创建 一 个 副标题 对 象 【〈 任 何 
Title 类 的 子 类 ) ， 然 后 将 该 对 象 加 到 图 表 上 即 可 。 代 码 如 下 


TextTitle subtitle1 = new TextTitle("A Subtitle"); 
jfreechart.addSubtitle(subtitle1); 


我 们 可 以 在 图 表 上 添加 任何 数量 的 副标题 ， 但 是 紧急 我 们 添加 的 副标题 越 多 ， 图 表 
画图 的 区 域 就 越 小 。 


修改 一 个 已 有 的 副标题 ， 我 们 需要 先 获得 副标题 的 一 个 引用 。 代 码 如 下 


Title subtitle = jfreechart.getSubtitle(0); 


在 我 们 改变 副标题 属性 之 前 ， 我 们 需要 将 Title 的 引用 转换 成 我 们 需要 的 适当 的 子 类 
类 型 。 


我 们 可 以 使 用 getSubtitleCount() 方 法 获得 副标题 的 数量 。 


9.2.5 设置 图 表 背 景 闫 色 


我 们 可 以 使 用 Cea onde a e e E 背景 闫 色 ( 注意， 我们 也 可 以 
设置 我 们 图 区 的 背景 颜色 ， 这 与 图 表 的 背景 颜色 不 同 Al) ° ble : 


jfreechart.setBackgroundPaint(Color.blue); 


我 们 可 使 用 Paint 接 口 的 任何 实现 作为 背景 颜色 的 设置 参数 ， 其 中 有 Color、 
GradientPaint ( #1 #1 é) 和 TexturePaint 等 。 代 码 如 下 


Paint p = new GradientPaint(0, 0, Color.white, 1000, 0, Color.gr 
een); 
jfreechart.setBackgroundPaint(p); 


我 们 可 以 设置 我 们 的 背景 颜色 为 null， 这 时 推荐 使 用 一 个 背景 图 片 来 设置 我 们 的 图 
表 。 


9.2.6 使 用 背景 图 片 
我 们 可 以 使 用 方法 setBackgroundlmage() 来 为 我 们 的 图 表 设 置 一 幅 背 景 图 表 。 


jfreechart.setBackgroundImage(JFreeChart.INFO.getLogo()); 


默认 的 ， 图 片 充 满 图 表 的 整个 背景 ， 图 片 失 昌 。 但 我 们 可 以 使 用 
setBackgroundlmageAlignment() 方 法 来 改变 图 片 不 充满 整个 背景 。 代 码 如 下 


jfreechart.setBackgroundImageAlignment (Align.TOP_LEFT); 


使 用 setBackgroundlmageAlpha() 方 法 ， 我 们 可 以 控制 图 片 的 透明 度 。 如 果 我 们 希 
望 图 片 只 填充 我 们 图 表 的 区 域 (区 域 包含 轴 ) > MA KA] EF BHF 景 图 片 添加 到 图 
表 的 图 区 。 代 码 如 下 (以 人 饼 图 为 例 ) 


PiePlot pieplot = (PiePlot) jfreechart.getPlot(); 
pieplot.setBackgroundImage( JFreeChart .INFO.getLogo( ) ) 


9.2.7 Rendering Hints (绘制 建议 ) 


Tea Dn 图 表 。 在 java2D 中 的 API 中 ， 我 们 可 以 提供 绘制 
建议 让 绘制 引擎 绘制 图 表 。JFreeChart 允 许 我 们 在 画图 表 时 ， 使 用 
setRenderingHints() 方 法 ， 将 绘制 建议 参数 传 入 java2D 的 API 中 。 


JFreeChart 还 提供 了 一 个 便利 反 锯 此 开关 方法 。 当 反 锯 此 开关 开 时 ， 图 表 会 绘制 出 
比较 光滑 的 图 表 ， 但 是 花费 的 时 间 要 长 。 代 码 如 下 


jfreechart.setAntiAlias(true); 


JFreeChart 和 画图 时 ， 上 默认 为 反 锯 部 开关 为 开 。 


9.3 图 区 属性 


9.3.1 概述 


JFreeChart 类 在 绘制 图 表 时 ， 将 大 部 分 工作 交 给 了 Plot 类 (图 形 绘 制 结构 ) 或 Plot 
的 子 类 。JFreeChart 类 的 getPlot() 方 法 返回 了 一 个 图 表 创 建 的 图 区 (plot) 的 引用 。 


Plot plot = jfreechart.getPlot(); 


我 们 需要 将 该 引用 转化 成 Plot 的 一 个 具体 子 类 。 例 如 


CategoryPlot plot = jfreechart.getCategoryPlot(); 


x 


XYPlot plot = jfreechart.getxXYPlot(); 


注意 : 如 果 plot 不 是 相应 的 类 ， 则 在 转化 的 时 候 ， 会 抛 出 ClassCastException 类 型 
转制 异常 。 


9.3.2 A RTX 
么 我 们 如 何 知 道 我 们 图 表 使 用 的 Plot 是 那个 子 类 呢 ? 作为 使 用 JFreeChart 的 经 
验 ， 分 清 那 些 图 表 使 用 CategoryPlot 和 那些 图 表 使 用 XYPlot 是 非常 清晰 的 。 


怀疑 ， 看 一 下 ChartFactory 类 的 源 代码 就 会 明白 每 个 类 型 的 图 表 是 如 何 放 在 一 
的 。 


9.3.3 设置 图 区 背景 闫 色 
我 们 可 以 使 用 方法 setBackgroundPaint() 设 置 图 区 的 背景 颜色 。 例 如 : 


Plot plot = jfreechart.getPlot(); 
plot .setBackgroundPaint(Color.white); 


我 们 可 使 用 Paint 接 口 的 任何 实现 作为 背景 凑 色 的 设置 参数 ， 其 中 有 Color、 
GradientPaint (渐变 颜色 ) 和 TexturePaint 等 。 同 时 ， 我 们 也 可 以 设置 背景 颜色 为 
null ° 


9.3.4 设置 背景 图 片 


我 们 可 以 使 用 方法 setBackgroundlmage() 为 图 区 设置 备 有 图 片 。 


Plot plot = jfreechart.getPlot(); 
plot .setBackgroundImage( JFreeChart .INFO.getLogo()); 


默认 的 ， 图 片 充 满 图 表 的 整个 背景 ， 图片 失 旧 。 但 我 们 可 以 改变 图 片 不 充满 整个 背 
景 ， 使 用 方法 是 setBackgroundlmageAlignment()。 


plot.setBackgroundImageAlignment (Align.BOTTOM_RIGHT); 


í Fl setBackgroundimageAlpha()7 * ° 我 们 可 以 控制 图 片 的 透 o 如果 我 们 硕 
望 图 片 充满 这 个 图 表 区 域 ， 那 么 我 们 需要 将 背景 图 片 添加 到 站 (前 
面 已 经 介绍 过 ) 。 


9.4 轴 属 性 


9.4.1 概述 


使 用 JFreeChart 创 建 的 大 部 分 图 表 都 带 有 两 个 轴 。X 轴 和 Y 轴 。 当 然 对 于 一 些 图 表 
( rite HHA) 根本 就 没有 轴 。 对 于 使 用 轴 的 图 表 来 说 ， 图 区 使 用 Axis 对 象 来 管理 
ah o 


9.4.2 获得 轴 对 象 引 用 


在 你 修改 轴 的 属性 之 前 ， 我 们 需要 先 获得 一 个 轴 的 引用 。 图 区 类 CategoryPlot 和 
XYPIlot 类 有 两 个 方法 getDomainAxis() 和 getRangeAxis() 分 别 是 获得 X 轴 Y 轴 对 象 。 
这 两 个 方法 返回 了 一 个 ValueAxis 对 象 的 引用 ， 除 了 在 使 用 CategoryPlot 的 情况 下 ， 
X 轴 使 用 的 是 CategoryAxis。 代 码 如 下 : 


// get an axis reference... 

CategoryPlot plot = jfreechart.getCategoryPlot(); 
CategoryAxis domainAxis = plot.getDomainAxis()j; 
// change axis properties... 
domainAxis.setLabel("Categories"); 
domainAxis.setLabelFont(someFont); 


CategoryAxis 和 ValueAxis 类 有 许多 不 同 的 子 类 。 有 时 我 们 需要 将 轴 对 象 引 用 转化 成 
具体 的 子 类 ， 为 了 获取 更 多 具体 的 属性 。 如 ， 如 果 我 们 想 获 得 y 轴 为 一 个 对 象 
NumberAxis。 代 码 如 下 : 


XYPlot plot = jfreechart.getXxYPlot(); 
NumberAxis rangeAxis = (NumberAxis) plot.getRangeAxis(); 
rangeAxis.setAutoRange(false) ; 


9.4.3 设置 轴 标 签 


我 们 使 用 方法 setLabel() 可 以 改变 轴 的 标签 o 如 果 我 们 不 想 在 图 表 的 轴 上 有 标签 
那么 我 们 就 设置 为 null 即 可 。 


我 们 可 以 使 用 Axis 类 定义 的 方法 setLabelFont(), setLabelPaint(), 和 
setLabellnsets() 改 变 标签 的 字体 、 颜 色 等 内 容 。 
9.4.4 改变 周边 标签 显示 方向 


当 图 区 在 左 侧 或 右 侧 画 一 个 轴 (水 平 轴 ) 时 ， 轴 标签 会 自动 旋转 90 度 ， 以 满足 小 空 
间 的 需要 。 如 果 我 们 希望 标签 也 水 平 ， 我 们 需要 修改 标签 的 角度 : 


XYPlot plot = jfreechart.getXYPlot(); 
ValueAxis axis = plot.getRangeAxis(); 
axis.setLabelAngle(Math.PI / 2.0); 


注意 角度 的 表示 使 用 约 度 (PI| 为 180 度 ) ° 


9.4.5 隐藏 刻度 标签 
隐藏 某 个 轴 的 刻度 标签 : 


CategoryPlot plot = jfreechart.getCategoryPlot(); 
ValueAxis axis = plot.getRangeAxis(); 
axis.setTickLabelsVisible(false) ; 


对 于 CategoryAxis， 方 法 setTickLabelsVisible(false) 隐 藏 种 类 标签 。 


9.4.6 隐藏 刻 度 符 号 
隐藏 菜 个 轴 的 刻度 符号 


XYPlot plot = jfreechart.getXYPlot(); 
Axis axis = plot.getDomainAxis(); 
axis.setTickMarksVisible(false); 


注意 category 轴 没有 刻度 符号 。 


9.4.7 设置 刻度 尺寸 


默认 的 ， 数 值 和 日 期 会 自动 选择 一 个 刻度 尺寸 ， 以 便 刻度 标签 不 会 重复 显示 。 但 我 
们 也 可 以 使 用 setTickUnit() 方 法 设置 我 们 自己 的 饿 刻度 单位 。 


9.4.8 指定 标准 的 数值 刻度 单位 


eur ace 方法 允许 我 们 设置 我 们 自己 的 刻度 单位 蔡 代 系统 自动 选择 刻 
度 danwi 的 机 制 。 最 普通 的 应 用 就 是 我 们 有 一 个 仅仅 显示 整数 的 数 轴 。 在 实例 pe ， 
我 们 不 想 让 0. 5 或 者 0 25 作 为 刻度 单位 。 在 NumberAxis 类 中 有 一 个 静态 方法 返 

系列 的 标准 整数 刻度 单位 : 


XYPlot plot = jfreechart.getxYPlot(); 

NumberAxis axis = (NumberAxis) plot.getRangeAxis(); 
TickUnitSource units = NumberAxis.createIntegerTickUnits(); 
axis.setStandardTickUnits(units); 


如 果 我 们 想 控 制 标准 的 刻度 单位 时 ， 我 们 可 以 自由 定制 自己 的 TickUnits 集 合 。 
9.4.9 指定 标准 的 日 期 刻度 单位 
类 似 于 上 一 节 内 容 ，DateAxis 类 也 有 一 个 setStandardTickUnits() 方 法 ， 来 设置 我 们 


的 刻度 单位 。 方 法 createStandardDateTickUnits() 为 DateAxis 返 回 了 一 个 缺 省 的 集 
合 。 同 时 我 们 也 可 以 创建 我 们 自己 的 标准 日 期 刻度 单位 。 


9.5 心得 体会 


9.5 心得 体会 


9.5.1 Title 子 类 如 下 图 : 


包 图 如 下 所 示 : 


(=) £8) jfreechart-1.0.6. jar - D:\mylib\jfree 
E- META-INF 
H- org. jfree. chart 
& 
由 CompositeTitle. class 
由 DateTitle. class 
由 ImageTitle. class 
由 LegendGraphic. class 
由 ta LegendL[temBlockContainer. class 
由 LegendTitle. class 
由 PaintScaleLegend. class 
由 TextTitle. class 


由 Title. class 
lt- org. jtree. chart. needle 


关系 类 图 如 下 : 





org. jfree. chart. title 














9.5.2 Plot% 
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9.5 心得 体会 


E-D jfreechart-1.0.6. jar - D:\mylib\jfree 
由 -号 META-INF 
H-H} org. jfree. chart 





由 CategoryMarker. class 

由 CategoryPlot. class 

Ef ColorPalette. class 

由 CombinedDomainCategoryPlot. cla: 
由 t CombinedDomainktYPlot. class 

由 CombinedRangeCategoryPlot. clas: 
由 CombinedRangeXY¥Plot. class 

由 CompassPlot. class 

由 to ContourPlot. class 

由 ta ContourPlotUtilities. class 

由 ContourValuePlot. class 

由 CrosshairState. class 

由 DatasetRenderinellr der. class 

由 hy DefaultDrawingSupplier. class 

= - = 一 


类 结构 图 如 下 : 





1289 


10 动态 图 (Dynamic Charts ) 


10.1 简介 


10.1 简介 


为 了 说 明 使 用 JFreeChart 创 建 “ 动 态 "的 图 表 ， 本 章节 阅 述 了 一 个 简单 的 应 用 说 明 这 
个 过 程 ， 该 应 用 为 动态 刷新 JVM 内 存 显示 已 使 用 和 未 使 用 情况 。 如 下 图 10.1 


Nemory Usage Demo 


3,000,000 |) 


JVM Memory Usage 


= 2,000,000 
E 
E 
= 1,000,000 || 
ole 
15:10:22.500 15:10:23.000 15:10:23.500 
Time 


= Total Memory == Free Memory 


如 图 10.1 一 个 简单 的 “动态 "实例 (参考 : MemoryUsageDemo.java) 。 
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10.2 知识 背景 


10.2.1 事件 监听 


JFreeChart 使 用 监听 机 制 来 响应 其 他 chart 组 件 改 变 的 响应 。 例 如 ， 不 论 数 据 源 在 何 
时 发 生 更 新 ， 一 个 DatasetChangeEvent 事 件 总 被 发 送 给 已 注册 进 数据 源 的 监听 


na 


响应 触发 发 生 一 系列 事件 : 


© 图 区 监听 到 数据 源 改 变 的 通知 。 如 果 需 要 更 新 轴 的 值 ， 然 后 将 
人 注册 的 监听 器 。 

oe 图 表 监 听 到 图 区 更 改 事件 的 通知 ， 然 后 将 ChartChangeEvent 事 件 通知 给 所 有 
注册 的 监听 器 。 

e 最 后 ，ChartPanel 接 受到 该 面板 上 显示 的 图 表 的 更 改 事件 ，ChartPanel 根 据 响 
应 的 事件 画 出 定 全 重新 画 ， 而 不 是 仅仅 更 新 数据 。 


所 有 图 表 或 者 其 他 子 控件 改变 发 生 的 事件 过 程 都 遵循 上 面 的 过 程 。 





10.2.2 性 能 优化 


关于 性 能 优化 ， 我 们 必须 明白 JFreeChart 不 会 产生 实时 图 表 。 每 次 数据 源 的 更 新 ， 
ChartPanel 都 需要 重新 画 全 部 的 图 表 。 


性 能 优化 通常 是 非常 困难 的 。 比如，JFreeChart 调 用 图 像 2D 的 API 提 取 最 新 变更 的 
点 ， 从 而 只 画 更 新 的 点 。 我 们 使 用 JFreeChart 完 成 这 个 实时 过 程 的 实例 将 限制 了 “每 
秒 产 生 页 面 " 的 数量 。 产 生 数 量 的 大 小 是 否 是 一 个 瓶颈 的 关键 问题 ， 主 要 取决 我 们 我 
们 画图 表 所 依赖 的 数据 ， 应 用 的 环境 和 操作 环境 。 


10.3 实例 应 用 


10.3.1 概述 
实例 MemoryUsageDemo.java 文 档 可 以 从 下 面 的 链接 中 获得 : 
http://www.object-refinery.com/jfreechart/premium/index.html 


页 面 需 要 输入 购买 JFreeChart 开 发 指南 时 需要 的 用 户 名 和 密码 。 


10.3.2 创建 一 个 dataset 


创建 的 实例 代码 数据 源 ， 包 含 了 一 个 单一 的 时 序 集合 ， 集 合 内 有 两 个 TimeSeries 对 
象 (一 个 是 计算 总 内 存 ， 另 一 个 是 计算 剩余 内 存 ) 。 代 码 如 下 : 


this.total = new TimeSeries("Total", Millisecond.class); 
this.total.setMaximumItemAge(30000) ; 

this.free = new TimeSeries("Free", Millisecond.class); 
this. free.setMaximumItemAge( 30000) ; 

TimeSeriesCollection dataset = new TimeSeriesCollection(); 
dataset.addSeries(this.total); 
dataset.addSeries(this.free); 


每 个 时 间 系 列 的 maximumltemAge 属 性 设置 为 30000 毫 秒 〈30 秒 ) 。 因 此 任何 时 候 
添加 到 新 系列 的 新 数据 ， 都 是 30 秒 前 记录 的 老 数据 。 


10.3.3 创建 一 个 图 表 
图 表 的 创建 (定制 ) 都 遵循 所 有 图 表 创建 的 标准 模式 。 创 建 动 态 图 也 是 一 样 ， 没 有 


任何 特殊 的 步 又。 除了 我 们 将 autoRange 属 性 设置 为 true 之 外 。 同 时 ， 这 也 有 利于 
维护 图 表 使 用 的 数据 源 的 引用 。 


10.3.4 更 新 一 个 dataset 


在 本 实例 演示 中 ， 通 过 向 两 个 时 序 图 添加 的 数据 来 更 新 数据 源 ， 该 数据 的 添加 有 一 
个 独立 的 线程 Timer 管 理 。 代 码 如 下 : 


class DataGenerator extends Timer implements ActionListener { 
DataGenerator(int i) { 
super(i, null); 
addActionListener(this); 


public void actionPerformed(ActionEvent actionevent) { 
long 1 = Runtime.getRuntime().freeMemory(); 
long 1_0_ = Runtime.getRuntime().totalMemory(); 
MemoryUsageDemo. this.addTotalObservation((double) 1_0_); 
MemoryUsageDemo. this.addFreeObservation((double) 1); 


注意 JFreeChart 在 画图 表 和 数据 源 更 新 代码 之 间 没 有 使 用 线程 同步 ， 因 此 是 不 安全 
的 。 另 一 点 需要 注意 的 是 ， 曾 做 过 一 个 关于 JFreeChart 内 存 泄露 问题 的 测试 ， 将 
JFreeChart 的 实例 在 一 个 机 器 上 连续 运行 6 天 。 随 着 图 表 的 不 断 更 新 ， 我 们 就 可 以 
看 到 垃圾 收集 器 所 产生 的 影响 。 六 天 之 后 ， 发 现 总 内 存 的 使 用 量 保持 不 变 。 当 
JFreChart 产 生 并 丢弃 的 临时 对 象 〈 垃 圾 对 象 ) 时 ， 剩 余 可 用 内 存 减 少 了 。 增 加 的 
使 用 内 存量 是 垃圾 收集 器 工作 时 所 使 用 的 。 


10.3.5 全 部 代码 
下 面 是 全 部 的 实例 代码 : 


/* MemoryUsageDemo - Decompiled by JODE 
* Visit http://jode.sourceforge.net/ 

ay, 

package demo; 

import java.awt.BasicStroke; 

import java.awt.BorderLayout; 

import java.awt.Color; 

import java.awt.Font; 

import java.awt.event.ActionEvent; 
import java.awt.event.ActionListener; 
import java.awt.event.WindowAdapter; 
import java.awt.event.WindowEvent; 
import javax.swing.BorderFactory; 
import javax.swing. JFrame; 

import javax.swing. JPanel; 

import javax.swing.Timer; 

import org.jfree.chart.ChartPanel; 
import org.jfree.chart.JFreeChart; 
import org.jfree.chart.axis.DateAxis; 
import org.jfree.chart.axis.NumberAxis; 
import org.jfree.chart.plot.XYPlot; 
import org.jfree.chart.renderer.xy.XYLineAndShapeRenderer ; 
import org.jfree.data.time.Millisecond; 
import org.jfree.data.time.TimeSeries; 
import org.jfree.data.time.TimeSeriesCollection; 


import org.jfree.ui.RectangleInsets; 
public class MemoryUsageDemo extends JPanel { 

private static final long serialVersionUID = 677671283835949 
8649L; 

private TimeSeries total; 

private TimeSeries free; 

/* synthetic */ 

static Class class$org$jfree$data$time$Millisecond; 

class DataGenerator extends Timer implements ActionListener 


private static final long serialVersionUID = 1L; 
DataGenerator(int i) { 

super(i, null); 

addActionListener(this); 


public void actionPerformed(ActionEvent actionevent) { 
long 1 = Runtime.getRuntime().freeMemory(); 
long 1 0 = Runtime.getRuntime().totalMemory(); 
MemoryUsageDemo. this.addTotalObservation((double) 1_ 
0_); 
MemoryUsageDemo. this.addFreeObservation((double) 1); 
} 
} 
public MemoryUsageDemo(int i) { 
super(new BorderLayout()); 
total = new TimeSeries( 
"Total Memory", 
(class$org$jfree$data$time$Millisecond == null ? (cl 
ass$org$jfree$data$time$Millisecond = class$("org.jfree.data.tim 
e.Millisecond") ) 
class$org$jfree$data$time$Millisecond) ); 
total.setMaximumItemAge((long) i); 
free = new TimeSeries( 
"Free Memory", 
(class$org$jfree$data$time$Millisecond == null ? (cl 
ass$org$jfree$data$time$Millisecond = class$("org.jfree.data. tim 
e.Millisecond") ) 
class$org$jfree$data$time$Millisecond) ); 
free.setMaximumItemAge((long) i); 
TimeSeriesCollection timeseriescollection = new TimeSeri 
esCollection(); 
timeseriescollection.addSeries(total); 
timeseriescollection.addSeries(free); 
DateAxis dateaxis = new DateAxis("Time"); 
NumberAxis numberaxis = new NumberAxis("Memory"); 
dateaxis.setTickLabelFont(new Font("SansSerif", ©, 12)); 
numberaxis.setTickLabelFont(new Font("SansSerif", ©, 12) 
); 
dateaxis.setLabelFont(new Font("SansSerif", 0, 14)); 
numberaxis.setLabelFont(new Font("SansSerif", ©, 14)); 
XYLineAndShapeRenderer xylineandshaperenderer = new XYLi 
neAndShapeRenderer ( 
true, false); 


xylineandshaperenderer.setSeriesPaint(0, Color.red); 
xylineandshaperenderer.setSeriesPaint(1, Color.green); 
xylineandshaperenderer.setSeriesStroke(0, new BasicStrok 
e(3.0F, 0, 2)); 
xylineandshaperenderer.setSeriesStroke(1, new BasicStrok 
e(3.0F, 0, 2)); 
XYPlot xyplot = new XYPlot(timeseriescollection, dateaxi 
s, numberaxis, 
xylineandshaperenderer ); 
xyplot.setBackgroundPaint(Color.lightGray); 
xyplot.setDomainGridlinePaint(Color.white); 
xyplot.setRangeGridlinePaint(Color.white); 
xyplot.setAxisOffset(new RectangleInsets(5.0, 5.0, 5.0, 
5.0)); 
dateaxis.setAutoRange(true); 
dateaxis.setLowerMargin(0.0); 
dateaxis.setUpperMargin(0.0); 
dateaxis.setTickLabelsVisible(true); 
numberaxis.setStandardTickUnits(NumberAxis.createInteger 
TickUnits()); 
JFreeChart jfreechart = new JFreeChart("JVM Memory Usage 
" new Font( 
"SansSerif", 1, 24), xyplot, true); 
jfreechart.setBackgroundPaint(Color.white); 
ChartPanel chartpanel = new ChartPanel(jfreechart, true) 
了 
chartpanel.setBorder (BorderFactory.createCompoundBorder ( 
BorderFactory 
.createEmptyBorder(4, 4, 4, 4), BorderFactory 
.createLineBorder(Color.black))); 
add(chartpanel); 
} 
private void addTotalObservation(double d) { 
total.add(new Millisecond(), d); 
} 
private void addFreeObservation(double d) { 
free.add(new Millisecond(), d); 


public static void main(String[] strings) { 
JFrame jframe = new JFrame("Memory Usage Demo"); 
MemoryUsageDemo memoryusagedemo = new MemoryUsageDemo (30 
000); 
jframe.getContentPane().add(memoryusagedemo, "Center"); 
jframe.setBounds(200, 120, 600, 280); 
jframe.setVisible(true); 
memoryusagedemo.new DataGenerator(100).start(); 
jframe.addwWindowListener(new WindowAdapter() { 
public void windowClosing(WindowEvent windowevent) { 
System.exit(0); 
} 
}); 
} 


/* synthetic */static Class class$(String string) { 


Class var_class; 


ye 
var_class = Class.forName(string); 


} catch (ClassNotFoundException classnotfoundexception) 


{ 
throw new NoClassDefFoundError(classnotfoundexceptio 
n.getMessage()); 


return var_class; 


11 图 表 工具 条 (Tooltips ) 


11.1 概述 


JFreeChart 为 图 表 的 每 个 组 件 提供 了 一 套 产 生 、 收 集 和 显示 工具 条 的 机 制 。 本 章 主 
要 介绍 : 

o 如 何 产 生 图 表 工 具 条 (包括 定制 图 表 工 具 条 ) 

o 如 何 收 集 图 表 工 具 条 

o 如 何 显示 图 表 工 具 条 

e 如 何 隐 藏 图 表 工 具 条 


11.2 创建 图 表 工 具 条 
如 果 我 们 需要 使 用 图 表 工 具 条 ， 我 们 首先 确保 所 画 的 图 表 中 已 经 产生 图 表 工 具 条 。 


我 们 可 以 为 我 们 的 图 区 或 图 区 条 目 设 置 图 表 工 具 条 产生 器 。 在 下 面 的 相关 章节 里 
面 ， 我 们 将 了 解 如 何 为 一 个 图 表 设 置 一 个 图 表 工 具 条 。 


11.2.1 人 饼 图 
人 饼 图 类 PiePlot 使 用 PieToolTipGenerator 接 口 产 生 接 口 图 表 工 具 条 。 系 统 通过 了 该 接 


口 的 一 个 标准 实现 类 StandardPieToolTipGenerator。PiePlot 设 置 图 表 工具 条 的 方法 
如 下 : 


public void setToolTipGenerator(PieToolTipGenerator generator); 
该 方法 可 以 为 饼 图 设置 工具 条 产生 器 ， 如 果 设 置 null， 则 表示 没有 工具 条 。 


11.2.2 generated. 种 类 图 
种 类 图 表 一 包括 JFreeChart 创 建 最 多 的 直方 条 形 图 一 基于 CategoryPlot 类 并 使 用 
CategoryltemRenderer 来 画 每 一 个 数据 条 目 。Renderer 使 用 接口 


CategoryToolTipGenerator 的 指定 方法 来 获得 图 表 工 具 条 。 为 种 类 图 区 条 目 设置 图 
表 工 具 条 产生 器 ， 使 用 类 AbstractCategoryltemRenderer 的 方法 : 


public void setToolTipGenerator(CategoryToolTipGenerator generat 
or); 


该 方法 可 以 为 饼 图 设置 工具 条 产生 器 ， 如 果 设 置 null， 则 表示 没有 工具 条 。 


11.2.3 XY K 
XY 图 表 一 包括 JFreeChart 创 建 的 散 点 图 和 时 序 图 一 基于 类 XYPlot 并 使 用 


XYltemRenderer 画 出 每 一 个 数据 条 目 。Renderer 使 用 一 个 XYToolTipGenerator 产 
生 图 表 工 具 条 。 


设置 XY 图 区 条 目的 工具 条 ， 使 用 在 AbstractXYltemRenderer 定 义 的 方法 : 


public void setToolTipGenerator(XYToolTipGenerator generator); 


如 果 设 置 产 生 器 为 null， 表 示 没 有 图 表 工 具 条 产生 器 。 


11.2 创建 图 表 工 具 条 
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11.3 收集 图 表 工 具 条 


使 用 ChartRenderinglnfo 类 可 收集 图 表 工 具 条 信息 ， 以 及 图 表 的 其 他 信息 。 我 们 首 
先 要 向 JFreeChart 的 draw() 方 法 传 入 该 类 实例 ， 否 则 图 表 工 具 条 信息 将 不 被 记录 
(即便 是 产生 器 已 经 被 注册 到 图 区 的 数据 条 目 中 ) o 


幸运 的 是 ，ChartPanel 会 自动 的 处 理 图 表 工 具 条 的 收集 。 因 此 如 果 我 们 使 用 
ChartPanel 显 示 我 们 的 图 表 ， 就 不 用 担心 图 表 工 具 条 的 收集 一 因为 ChartPanel 已 经 
为 我 们 收集 了 。 


11.4 显示 图 表 工 具 条 


使 用 ChartPanel 类 创建 我 们 的 图 表 时 ， 图 表 工 具 条 会 自动 显示 出 来 。 并 且 你 可 以 为 
图 区 (或 者 图 区 的 renderer) 设置 一 个 图 表 工 具 条 。 


我 们 可 是 使 用 类 的 方法 设置 显示 或 隐藏 图 表 工 具 条 。 方 法 如 下 : 


public void setDisplayToolTips(boolean flag); 


11.5 隐藏 图 表 工 具 条 


最 有 效 的 方式 就 是 将 图 表 工 具 条 条 设置 为 null。 确保 没有 任何 图 表 工 具 条 信 息 产生 ， 
这 样 可 以 节省 内 存 同时 提供 处 理 速 度 (特别 是 对 于 大 数据 源 时 ， 非 常 有 好 处 ) © 


我 们 可 是 使 用 上 节 讲 的 方法 使 用 ChartPanele 类 设置 图 表 工 具 条 的 隐藏 。 


11.6 定制 图 表 工 具 条 


我 们 可 以 通过 相应 的 图 表 工 具 条 产生 器 接口 对 每 一 个 图 表 工 具 条 进行 文本 的 各 种 操 
作 。 


12 图 表 条 目标 签 (Item Label) 


12.1 简介 


12.1.1 概述 


对 于 大 多 数 的 图 表 类 型 来 说 ，JFreeChart 多 许 我 们 在 图 表 的 每 个 条 目 上 、 或 者 内 
部 、 或 者 附近 显示 条 目标 签 。 例 如 ， 下 图 12.1 在 每 个 条 形 图 上 显示 出 了 昌 实 的 值 。 


= Item Label Demo 1 TBR) 


Item Label Demo 1 
93.0 








A121 显示 数组 的 条 形 图 (参考 : ) 
本 章 主要 讲述 : 


如 何 让 条 目标 签 可 视 ( 仅 限 于 支持 条 目标 签 的 图 表 类 型 ) 
如 何 改变 条 目标 签 的 外 观 (字体 和 颜色 ) 

如 何 指定 条 目标 签 的 位 置 

如 何 定制 条 目标 签 的 文本 

忠告 : 我 们 使 用 上 面 的 特征 时 ， 要 谨 惯 。 图 表 是 期 望 用 来 分 析 总 结 数据 的 一 一 如 果 
我 们 觉得 在 图 表 上 显示 莫 实 数据 是 非常 有 必要 的 话 ， 那 我 们 的 数据 应 使 用 一 个 表格 
格式 显示 更 为 合适 。 





12.1.2 局 限 性 


在 当前 版 本 JFreeChart 中 ， 条 目标 签 的 使 用 是 有 很 多 局 限 性 的 : 


e 一 些 renderer 不 支持 条 目标 签 

e 轴 范 围 的 自动 调节 ， 忽 略 了 条 目标 签 的 自动 调整 一 一 如 果 图 表 的 周围 没有 足够 
的 空间 (使 用 方法 setUpperMargin() 或 setLowerMargin() 进 行 了 相应 的 调 
整 ) ， 那 么 一 些 图 表 条 目标 签 在 图 表 上 显示 不 出 来 。 


相信 ， 在 以 后 的 JFreeChart 版 本 中 ， 这 些 限 制 问 题 将 被 解决 。 





12.1 简介 
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12.2 显示 条 目标 签 


12.2.1 概述 


条 条 目标 签 默 认 是 不 显示 的 ， 因 此 我 们 需要 使 用 renderer 进 行 创建 和 显示 条 目标 签 。 
这 主要 有 以 下 两 个 步骤 : 


e 分 配 一 个 CategoryltemLabelGenerator 或 XYltemLabelGenerator 给 renderer 一 
这 是 一 个 负责 责 创建 标签 的 对 象 

e Zrenderer 2&7 受 置 一 个 标签 可 视 的 标志 。 可 以 针对 全 部 系列 进行 设置 ， 也 可 
以 针对 具体 的 每 一 个 系列 进行 设置 。 


此 外 ， 我 们 可 以 定制 条 目标 签 的 位 置 、 字 体 和 颜色 。 在 下 面 的 章节 里 我 们 将 详细 的 
介绍 。 


12.2.2 创建 一 个 条 目标 签 并 赋值 


使 用 renderer 分 配 的 一 个 标签 产生 器 创建 条 目标 签 (这 与 图 表 工 具 条 的 机 制 是 相同 
的 ) 。 


下 面 代 码 说 了 将 一 个 标签 产生 器 指派 给 CategoryltemRenderer : 


CategoryItemRenderer renderer = categoryplot.getRenderer(); 
CategoryItemLabelGenerator generator = new StandardCategoryItemL 
abelGenerator("{2}", new DecimalFormat("0.00")); 

renderer .setBaseItemLabelGenerator (generator); 


同样 的 ， 将 一 个 产生 器 指派 给 XYltemRenderer， 代 码 如 下 


XYPlot plot = (XYPlot) jfreechart.getPlot(); 
XYItemRenderer renderer = plot.getRenderer(); 
XYItemLabelGenerator generator = new StandardxYItemLabelGenerato 
r( 

"{2}", new DecimalFormat("0.00"), new DecimalFormat("0.00")) 


/ 
renderer .setBaseItemLabelGenerator (generator); 


我 们 可 以 在 标准 产生 器 的 构造 函数 中 定制 不 同 的 行为 。 当 然 了 ， 我 们 也 可 以 创建 我 
们 总 计 的 产生 器 ， 详 见 12.5.2 章 节 。 


12.2.3 所 有 的 系列 显示 条 目标 签 


方法 renderersetBaseltemLabelsVisible(false) 是 控制 着 条 目标 签 的 显示 。 对 于 
CategoryltemRenderer : 


CategoryItemRenderer renderer = categoryplot.getRenderer(); 
renderer .setBaseItemLabelsVisible(true); 


同样 对 于 : XYltemRenderer 


XYItemRenderer renderer = categoryplot.getRenderer(); 
renderer .setBaseItemLabelsVisible(true); 


一 旦 设置 ， 这 个 标志 优先 管 理 我 们 在 所 有 地 方 对 每 一 系列 做 的 设置 ， 主 要 为 了 应 用 
每 一 系列 的 设置 。 我 们 可 以 设置 个 标志 为 null ( 见 12.2.4 章 节 ) 
12.2.4 为 选择 的 系列 显示 条 目标 签 


我 们 可 以 控制 图 表 的 每 一 个 系列 的 条 目标 签 是 否 显 示 。 例 如 : 如 下 图 12.2 仅 显示 第 
一 系列 条 目标 签 。 
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如 图 12.2 显 示 第 一 系列 条 目标 签 
下 面 代 码 可 以 设置 如 上 效果 : 





CategoryItemRenderer renderer = categoryplot.getRenderer(); 
renderer .setBaseItemLabelGenerator(new StandardCategoryItemLabel 
Generator()); 

renderer.setBaseItemLabelsVisible(null); // clears the ALL serie 
s flag 

renderer.setSeriesItemLabelsVisible(0, true); 
renderer.setSeriesItemLabelsVisible(1, false); 


注意 : 上 面 代 码 中 对 全 部 的 系列 设置 为 null 一 这 一 点 非常 重要 ， 因 为 全 部 系列 的 标 
志 控制 每 一 个 系列 的 标志 。 


12.2.5 问题 与 解决 
如 果 按 照 上 面 的 步骤 操作 ， 你 仍然 未 看 见 条 目标 签 显示 在 图 表 上 ， 那 么 我 们 从 以 下 
几 个 方面 进行 考虑 : 


e Renderere 必 须 需 要 一 个 标签 产生 器 
条 目的 对 象 。 
e 一 些 renderer 不 支持 条 目标 签 (具体 参考 renderer 相 关 的 文档 ) 


这 是 一 个 用 来 创建 每 一 个 标签 的 文本 





12.3 条 目标 签 外 观 


12.3.1 概述 


我 们 可 以 通过 改变 条 目的 颜色 、 字 体 来 改变 图 表 条 目标 签 的 外 观 。 正 如 其 他 
renderer 属 性 一 样 ， 属 性 的 设置 可 以 是 全 部 的 系列 ， 可 以 是 具体 某 一 系列 。 


在 JFreeChart 目 前 的 版 本 中 ， ie ERA AS — 8 A 89 ye BK RAY o RAH ARIE 
置 标签 的 背景 颜色 ， 也 不 能 指定 标签 的 边框 。 这 些 在 以 后 的 版 本 中 会 得 到 解决 。 


12.3.2 改变 条 目标 签 的 字体 
为 了 在 所 有 的 系列 中 改变 条 目标 签 的 字体 ， 我 们 可 以 使 用 下 面 的 代码 : 


CategoryItemRenderer renderer = categoryplot.getRenderer(); 
renderer.setBaseItemLabelFont(new Font(" Z415", Font.PLAIN, 20)); 


同样 ， 也 可 以 为 单个 系列 设置 字体 : 


// add settings for individual series... 
renderer.setSeriesItemLabelFont(0, new Font("SansSerif", Font.PL 
AIN, 20)); 

renderer.setSeriesItemLabelFont(1, new Font("SansSerif", Font.PL 
AIN, 10)); 


注意 : renderer.setBaseltemLabelFont(null) 方 法 会 出 错 。 开 发 指南 显示 的 代码 有 错 
误 。 


12.3.3 改变 条 目标 签 的 颜色 


改变 条 目标 签 的 颜色 ， 我 们 可 以 使 用 下 面 的 代码 : 


CategoryItemRenderer renderer = categoryplot.getRenderer(); 
renderer.setBaseItemLabelPaint(Color.red); 


同样 的 ， 可 以 为 单独 每 一 系列 设置 颜色 : 


// add settings for individual series... 
renderer.setSeriesItemLabelPaint(0, Color.red); 
renderer.setSeriesItemLabelPaint(1, Color.blue); 


注意 : renderer.setBaseltemLabelPaint(null); 方 法 会 出 错 。 开 发 指南 显示 的 代码 有 
错误 。 


12.4 条 目标 签 位 置 


12.4.1 概述 


条 目标 签 的 位 置 是 通过 ltemLabelPosition 对 象 的 四 个 属性 来 控制 的 。 


我 们 可 以 通过 接口 CategoryltemRenderer 的 方法 来 独立 定义 条 目标 签 的 正 负 点 位 
置 : 


public void setBasePositiveItemLabelPosition(ItemLabelPosition p 
osition); 
public void setBaseNegativeItemLabelPosition(ItemLabelPosition p 
osition); 


理解 这 些 属性 如 何 影响 独立 标签 的 最 终 位 置 的 关键 是 了 解 JFreeChart 里 面条 目标 签 
的 特征 。 四 个 特征 是 : 


e 条 目标 签 点 
+ 文 本 点 
o 旋转 点 


决定 标签 的 起 始 位 置 

标签 里 的 文本 相对 于 条 目标 签 的 位 置 。 
标签 文本 旋转 的 点 位 置 
标签 的 旋转 角度 。 


些 的 详细 描述 在 下 一 章 详细 介绍 。 














12.4.2 条 目标 签 的 位 置 
设置 条 目标 签 位 置 的 目的 ， 主 要 是 为 了 找 出 标签 在 图 表 上 贴 向 数据 条 目的 一 个 点 


(x y) 位 置 。 are 图 表 时 ， 该 标签 也 被 画 在 该 点 处 。 更 多 的 信息 可 以 参考 
ltemLabelAnchor 文 档 。 


12.4.3 标签 文本 的 位 置 


标签 文本 的 位 置 ， 主 要 取决 于 上 节 讲 的 标签 位 置 。 我 们 可 以 讲 标签 文本 在 标签 里 设 
置 在 右上 部 、 或 左下 部 等 ， 更 多 的 信息 参见 TextAnchor 文 档 。 


运行 JCommon 包 内 的 Org. demo.package 下 面 的 DrawStringDemo 应 用 ， 可 以 更 好 
的 理解 标签 文本 在 标签 内 是 如 何 放 置 的 。 


12.4.4 标签 旋转 点 


在 标签 上 定义 了 一 个 旋转 点 ， 用 于 旋转 标签 。 在 DrawStringDemo 实 例 中 很 好 演示 
了 这 个 特征 。 


12.4.5 标签 旋转 角度 


旋转 角度 定义 了 标签 沿 旋转 点 旋转 的 角度 。 该 角度 为 弧度 。 


12.5 定制 条 目标 签 文本 


12.5.1 概述 


定制 条 目标 签 文本 ， ee 器 来 为 条 目标 签 创 建 
文本 。 如 果 要 想 完全 控制 标签 文本 的 控 惠 nee oe. 需 


要 实现 接口 ices ae o 

在 本 章节 里 ， 我 们 对 自 定 义 标签 器 技术 做 了 简要 的 讲述 ， 然 后 用 两 个 实例 来 说 明 该 
技术 过 程 。 

12.5.2 实现 一 个 自 定义 的 标签 产生 器 

开发 一 个 自 定 义 标 签 产 生 器 ， 我 们 需要 写 一 个 类 ， 该 类 必须 实现 
CategoryltemLabelGenerator 接 口 里 的 方法 。 


public String generateLabel(CategoryDataset dataset, int series, 
int category) 


该 renderer 调 用 该 方法 获得 一 个 标签 的 字符 串 ， 并 且 将 该 FA 串 传 入 到 当前 条 目的 
CategoryDataset、 序 列 和 种 类 。 这 就 意味 着 创建 这 个 标签 时 ， 我 们 拥有 完全 的 访 
问 权 限 。 

该 方法 可 以 返回 任意 字符 串 ， 因 此 我 们 格式 化 这 个 字符 串 。 如 果 我 们 不 想 显示 标 
Z o TAR E A null e 


在 下 面 的 两 个 例子 中 很 好 的 说 明了 这 个 特征 。 


12.6 实例 1 


12.6.1 概述 


在 第 一 个 实例 中 ， 目 的 就 是 当当 条 目的 值 大 于 某 个 限定 的 值 时 ， 就 显示 该 标签 。 如 
图 12.3 所 示 。 
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如 图 12.3 超过 茶 个 限定 值 显 示 条 目标 签 的 实例 
做 到 这 一 点 并 不 困难 ， 需 要 做 以 下 工作 : 


e 写 一 个 实现 接口 CategoryltemLabelGenerator 的 类 ， 并 且 实 现 
generateltemLabel() 方 法 。 该 方法 实现 如 果 条 目的 值 小 于 限定 值 时 ， 返 回 
null ° 

o 创建 该 类 的 实例 ， 将 该 实例 使 用 renderer 的 方法 setLabelGenerator() 设 置 到 
renderer 中 去 。 


12.6.2 源 代 码 


package demo; 

import java.awt.Color; 

import java.awt.Dimension; 

import java.awt.Font; 

import java.text.DecimalFormat; 

import java.text.NumberFormat; 

import javax.swing. JPanel; 

import org.jfree.chart.ChartFactory; 
import org.jfree.chart.ChartPanel; 
import org.jfree.chart. JFreeChart; 
import org.jfree.chart.axis.NumberAxis; 
import org.jfree.chart.labels.AbstractCategoryItemLabelGenerator 


了 
import org.jfree.chart.labels.CategoryItemLabelGenerator; 
import org.jfree.chart.labels.StandardCategoryItemLabelGenerator 


了 
import org.jfree.chart.labels.StandardxYItemLabelGenerator; 
import org.jfree.chart.labels.xXYItemLabelGenerator; 
import org.jfree.chart.plot.CategoryPlot; 
import org.jfree.chart.plot.PlotOrientation; 
import org.jfree.chart.plot.XYPlot; 
import org.jfree.chart.renderer.category.CategoryItemRenderer ; 
import org.jfree.chart.renderer.xy.XYItemRenderer ; 
import org.jfree.data.category.CategoryDataset; 
import org.jfree.data.category.DefaultCategoryDataset; 
import org.jfree.ui.ApplicationFrame; 
import org.jfree.ui.RefineryUtilities; 
public class ItemLabelDemo1 extends ApplicationFrame { 
static class LabelGenerator extends AbstractCategoryItemLabe 
1Generator 
implements CategoryItemLabelGenerator { 
private double threshold; 
public LabelGenerator(double d) { 
super("", NumberFormat.getInstance()); 
threshold = d; 
} 
public String generateLabel(CategoryDataset categorydata 
set, int i, 
int i © ) { 
String string = null; 
Number number = categorydataset.getValue(i, i_0_); 
if (number != null) { 
double d = number .doubleValue(); 
if (d &gt; threshold) 
string = number.toString(); 


} 


return string; 

} 

} 

public ItemLabelDemo1i(String string) { 
super(string); 
CategoryDataset categorydataset = createDataset(); 
JFreeChart jfreechart = createChart(categorydataset ); 
ChartPanel chartpanel = new ChartPanel(jfreechart); 
chartpanel.setPreferredSize(new Dimension(500, 270)); 
setContentPane(chartpanel); 

} 

private static CategoryDataset createDataset() { 
DefaultCategoryDataset defaultcategorydataset = new Defa 

ultCategoryDataset(); 

defaultcategorydataset.addValue(11.0, "Si", "C1"); 
defaultcategorydataset.addValue(44.3, "Si", "C2"); 
defaultcategorydataset.addValue(93.0, "S1", "C3"); 
defaultcategorydataset.addValue(35.6, "Si", "C4"); 
defaultcategorydataset.addValue(75.1, "Si", "C5"); 


return defaultcategorydataset; 
} 
private static JFreeChart createChart(CategoryDataset catego 
rydataset) { 
JFreeChart jfreechart = ChartFactory.createBarChart ( 
"Item Label Demo 1", "Category", "Value", categoryda 
taset, 
PlotOrientation.VERTICAL, false, true, false); 
jfreechart.setBackgroundPaint(Color.white); 
CategoryPlot categoryplot = (CategoryPlot) jfreechart.ge 
tPlot(); 
categoryplot.setBackgroundPaint(Color.lightGray) ; 
categoryplot.setDomainGridlinePaint(Color.white); 
categoryplot.setRangeGridlinePaint(Color.white) ; 
NumberAxis numberaxis = (NumberAxis) categoryplot.getRan 
geAxis(); 
numberaxis.setUpperMargin(0.15); 
return jfreechart; 


public static JPanel createDemoPanel() { 
JFreeChart jfreechart = createChart(createDataset()); 
return new ChartPanel(jfreechart); 


public static void main(String[] strings) { 
ItemLabelDemoi itemlabeldemo1 = new ItemLabelDemoi( "Item 
Label Demo 1"); 
itemlabeldemo1.pack(); 
RefineryUtilities.centerFrameOnScreen(itemlabeldemo1) ; 
itemlabeldemoi.setVisible(true); 


12.7 实例 2 


12.7.1 概述 


在 本 实例 中 ， 目 的 是 在 每 个 系列 的 标签 上 显示 出 值 和 百分比 值 (这 个 百分比 值 ， 这 
个 系列 在 某 一 部 分 的 条 形 直 方 图 或 全 部 条 形 直 方 图 的 总 值 中 的 比值 ) 。 如 下 图 12.4 
所 示 。 
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图 12.4 带 有 比值 的 直方 图 

该 实现 中 ， 标 签 产 生 器 计算 出 百分比 。 如 果 传 入 构造 函数 的 是 一 个 种 类 索引 ， 那 么 
这 个 百分比 的 基数 就 是 指定 种 类 的 当前 系列 的 值 。 如 果 种 类 索引 是 无 效 的 ， 那 么 这 
个 基数 就 是 指定 种 类 的 全 部 系列 总 和 。 
标签 产生 器 会 默认 创建 一 个 百分比 格式 
力 o 


一 种 比较 成 熟 的 格式 ， 提 供 格 式 化 能 





12.7.2 源 代 码 


package demo; 

import java.awt.Color; 

import java.awt.Dimension; 

import java.text.NumberFormat; 

import javax.swing. JPanel; 

import org.jfree.chart.ChartFactory; 
import org.jfree.chart.ChartPanel; 

import org.jfree.chart. JFreeChart; 

import org.jfree.chart.axis.AxisLocation; 
import org.jfree.chart.axis.NumberAxis; 
import org.jfree.chart.labels.AbstractCategoryItemLabelGenerator 


T 


import org.jfree.chart.labels.CategoryItemLabelGenerator; 
import org.jfree.chart.plot.CategoryPlot; 
import org.jfree.chart.plot.PlotOrientation; 
import org.jfree.chart.renderer.category.CategoryItemRenderer ; 
import org.jfree.data.category.CategoryDataset; 
import org.jfree.data.category.DefaultCategoryDataset; 
import org.jfree.ui.ApplicationFrame; 
import org.jfree.ui.RefineryUtilities; 
public class ItemLabelDemo2 extends ApplicationFrame { 
static class LabelGenerator extends AbstractCategoryItemLabe 
1Generator 
implements CategoryItemLabelGenerator { 
private Integer category; 
private NumberFormat formatter = NumberFormat.getPercent 
Instance(); 
public LabelGenerator(int i) { 
this(new Integer(i)); 


public LabelGenerator(Integer integer) { 
super("", NumberFormat.getInstance()); 
category = integer; 
} 
public String generateLabel(CategoryDataset categorydata 
set, int i, 
int i © ) { 
String string = null; 
double d = 0.0; 
if (category != null) { 
Number number = categorydataset 
.getValue(i, category.intValue()); 
d = number .doubleValue(); 
} else 
d = calculateSeriesTotal(categorydataset, i 
Number number = categorydataset.getValue(i, i_© 
if (number != null) { 
double d_1_ = number .doubleValue(); 
string = (number.toString() + " (" + formatter.f 
ormat(d 1 / d) + ")"); 


); 
a) 


return string; 

} 

private double calculateSeriesTotal(CategoryDataset cate 
gorydataset, 

ANE a E 

double d = 0.0; 

for (int i_2_ = 0; i_2_ &lt; categorydataset.getColumnCo 
NEO a e a a 

Number number = categorydataset.getValue(i, i_2_); 


if (number != null) 

d += number .doubleValue(); 
} 

return d; 


} 


} 
public ItemLabelDemo2(String string) { 


super(string); 
CategoryDataset categorydataset = createDataset(); 
JFreeChart jfreechart = createChart(categorydataset ); 
ChartPanel chartpanel = new ChartPanel(jfreechart); 
chartpanel.setPreferredSize(new Dimension(500, 270)); 
setContentPane(chartpanel); 
} 
private static CategoryDataset createDataset() { 
DefaultCategoryDataset defaultcategorydataset = new Defa 
ultCategoryDataset(); 
defaultcategorydataset.addValue(100.0, "Si", "C1"); 
defaultcategorydataset.addValue(44.3, "S1", "C2"); 
defaultcategorydataset.addValue(93.0, "Si", "C3"); 
defaultcategorydataset.addValue(80.0, "S2", "C1"); 
defaultcategorydataset.addValue(75.1, "S2", "C2"); 
defaultcategorydataset.addValue(15.1, "S2", "C3"); 
return defaultcategorydataset; 
} 
private static JFreeChart createChart(CategoryDataset catego 
rydataset) { 
JFreeChart jfreechart = ChartFactory.createBarChart ( 
"Item Label Demo 2", "Category", "Value", categoryda 
taset, 
PlotOrientation.HORIZONTAL, true, true, false); 
jfreechart.setBackgroundPaint(Color.white); 
CategoryPlot categoryplot = (CategoryPlot) jfreechart.ge 
tPlot(); 
categoryplot.setBackgroundPaint(Color.lightGray) ; 
categoryplot.setDomainGridlinePaint(Color.white); 
categoryplot.setRangeGridlinePaint(Color.white); 
categoryplot.setRangeAxisLocation(AxisLocation.BOTTOM_OR 
_LEFT); 
NumberAxis numberaxis = (NumberAxis) categoryplot.getRan 
geAxis(); 
numberaxis.setUpperMargin(0.25); 
CategoryItemRenderer categoryitemrenderer = categoryplot 
.getRenderer(); 
categoryitemrenderer .setBaseItemLabelsVisible(true); 
categoryitemrenderer .setBaseItemLabelGenerator(new Label 
Generator ( 
(Integer) null)); 
return jfreechart; 
} 
public static JPanel createDemoPanel() { 
JFreeChart jfreechart = createChart(createDataset()); 
return new ChartPanel(jfreechart); 
} 
public static void main(String[] strings) { 
ItemLabelDemo2 itemlabeldemo2 = new ItemLabelDemo2("Item 
Label Demo 2"); 
itemlabeldemo2.pack(); 


RefineryUtilities.centerFrameOnScreen(itemlabeldemo2) ; 
itemlabeldemo2.setVisible(true); 


13 多 轴 和 数据 源 图 表 (Multi Axis and Dataset) 


13.1 简介 


J FreeChart 在 CategoryPlot 和 XYPlot 类 中 支持 多 轴 和 数据 源 显 示 。 我 们 利用 这 个 特 
征 可 以 在 一 个 图 表 上 显示 两 个 或 多 个 数据 源 数据 ， 但 对 于 数据 包含 的 数据 有 巨大 差 
距 时 留 有 一 定 的 余地 。 如 图 13.1 所 示 。 
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图 13.1 具有 多 轴 的 图 表 


典型 的 ， 使 用 JFreeChart 构 建 图 表 时 ， 图 表 有 一 个 单数 据 源 、 单 renderer、 单 X/Y 轴 
的 图 区 最 为 常见 。 然 而 ， 在 一 个 图 区 上 添加 多 个 数据 源 、 多 个 renderer 和 多 个 轴 也 
是 可 能 的 。 在 本 章 的 实例 中 ， 展 示 了 如 何在 一 个 图 区 上 显示 其 他 额外 的 数据 源 、 
renderer 和 轴 。 
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13.2 实例 


13.2.1 简介 


MultipleAxisDemo1.java 例 子 提 供 了 一 个 很 好 的 实例 演示 如 何在 一 个 图 表 上 创建 多 
轴 的 应 用 。 本 章 在 每 一 步 的 代码 中 提供 了 很 多 建议 ， 详 见 后 面 的 章节 。 


13.2.2 创建 一 个 图 表 


创建 一 个 具有 多 轴 、 多 数据 源 、 多 renderer 的 图 表 ， 我 们 首先 要 创建 一 个 常规 的 图 
表 (例如 使 用 ChartFactory 类 创建 ) 。 在 本 实例 中 ， 创 建 了 一 个 时 序 图 ， 代 码 如 
F: 


XYDataset dataset1 = createDataset("Series 1", 100.0, new Minute 
(), 200); 
JFreeChart chart = ChartFactory.createTimeSeriesChart ( 

"Multiple Axis Demo 1", 

"Time of Day", 

"Primary Range Axis", 

dataseti1, 

true, 

true, 

false 


); 


13.2.3 添加 额外 的 轴 
如 果 在 图 区 上 添加 额外 的 轴 ， 我 们 使 用 setRangeAxis() 方 法 来 添加 : 


NumberAxis numberaxis = new NumberAxis("Range Axis 2"); xyplot.s 
etRangeAxis(1, numberaxis); 
xyplot.setRangeAxisLocation(1, AxisLocation.BOTTOM_OR_LEFT); 


方法 setRangeAxis() 是 用 来 添加 图 区 的 轴 ， 注 意 轴 的 索引 1 已 经 被 使 用 一 我 们 添加 
其 他 轴 时 ， 通 过 增加 该 索引 来 添加 新 轴 。 方 法 setRangeAxisLocation() 允 许 我 们 指 
定 轴 出 现 的 位 置 (使 用 AxisLocation 类 ) 。 我 们 添加 的 轴 可 以 跟 主 坐标 轴 同 一 边 ， 
或 者 在 对 立 边 。 例 如 : 如 果 指 定 的 是 AxisLocation.BOTTOM_OR_LEFT， 这 意味 着 
如 果 图 区 的 方向 是 垂直 的 话 ， 将 在 右边 添加 了 一 个 Y 轴 ， 如 果 图 区 的 方向 是 水 平 的 
话 ， 将 在 底部 添加 一 个 Y 轴 。 


在 这 里 ， 图 表 上 每 一 添加 多 余 的 数据 源 ， 因 此 如 果 我 们 显示 该 图 表 ， 我 们 将 看 到 图 
上 显示 多 轴 ， 但 轴 上 无 数据 显示 。 


13.2.4 添加 一 个 额外 的 数据 源 


在 图 区 上 添加 一 个 额外 的 数据 源 ， 使 用 setDataset() 方 法 : 


XYDataset xydataset 0 = createDataset("Series 2", 1000.0, 
new Minute(), 170); 
xyplot.setDataset(1, xydataset_0_); 


缺 省 的 ， 数 据 源 将 使 用 主轴 来 显示 数据 。 如 果 使 数据 源 在 另外 的 轴 上 显示 数据 ， 需 
使 用 方法 mapDatasetToDomainAxis() 和 mapDatasetToRangeAxis()。 这 两 个 方法 接 
受 两 个 参数 ， 第 一 个 参数 是 数据 源 的 索引 ， 第 二 个 是 轴 的 索引 。 


13.2.5 添加 一 个 额外 的 renderer 


当 我 们 添加 一 个 数据 源 时 ， 通 常 为 该 数据 源 添加 一 个 附加 的 renderer 也 是 非常 有 意 
义 的 。 使 用 方法 setRenderer() : 


StandardXYItemRenderer standardxyitemrenderer = new StandardXYIt 
emRenderer(); 


xyplot.setRenderer(1, standardxyitemrenderer); 


方法 的 第 一 个 参数 为 上 节 中 添加 的 数据 源 的 索引 。 注 意 : 如 果 我 们 不 想 为 数据 源 指 
定 一 个 附加 的 rendere， 系 统 将 默认 使 用 主 renderer， 这 样 系列 的 颜色 就 会 在 主 数 据 
源 和 附加 数据 源 之 间 共 享 。 


13.3 建议 和 技巧 


当 我 们 使 用 多 轴 图 表 时 ， 我 们 需要 为 系列 对 应 的 轴 提 供 一 些 可 视 化 的 建议 。 上 比如 在 
例子 MultipleAxisDemo1.java 中 轴 标 签 的 颜色 与 系列 颜色 是 相 匹 配 的 。 


可 以 从 下 面 的 实例 中 学 习 更 多 的 技巧 : 


DualAxisDemo1.java 
DualAxisDemo2.java 
DualAxisDemo3.java 
DualAxisDemo4.java 
MultipleAxisDemo1.java 
MultipleAxisDemo2.java 
MultipleAxisDemo3.java 


14 组 合 图 表 (Combined Charts ) 


14.1 简介 
JFreeChart 支 持 几 个 图 区 类 (可 以 管理 着 多 个 子 类 ) 组 合 而 成 的 图 表 。 图 区 类 可 以 
管理 几 个 子 类 : 


e CombinedDomainCategoryPlot / CombinedRangeCategoryPlot 
e CombinedDomainxYPlot / CombinedRangexyYPlot ; 


本 章 使 用 几 个 实例 说 明了 JFreeChart 创 建 组 合 图 表 时 的 便利 性 。 


14.2 组 合 X 种 类 图 区 


14.2.1 概述 


组 合 主 域 种 类 图 区 就 是 在 一 个 图 区 上 显示 两 个 或 者 多 个 子 图 区 (CategoryPlot 实 
例 ) ， 共 享 一 个 X 轴 的 图 区 。 每 个 子 图 区 维护 自己 的 Y 轴 。 实 例如 图 14.1 所 示 。 
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如 图 14.1 组 合 X 种 类 图 区 (共享 X 轴 ) 
显示 图 表 可 以 是 水 平 的 ， 也 可 以 是 重 直 方向 的 一 实例 演示 的 是 牌 直 的 图 表 。 








14.2.2 构建 图 表 


提供 了 一 个 很 好 的 例子 ， 演 示 如 何 创 建 该 图 表 的 类 型 。 关 键 的 步骤 是 创建 
CombinedDomainCategoryPlot 实 例 ， 然 后 添加 两 个 子 图 区 : 


CategoryAxis domainAxis = new CategoryAxis("Category"); 
CombinedDomainCategoryPlot plot = new CombinedDomainCategoryPlot 
(domainAxis) ; 
plot.add(subploti, 2); 
plot.add(subplot2, 1); 
JFreeChart result = new JFreeChart( 

"Combined Domain Category Plot Demo", 

new Font("SansSerif", Font.BOLD, 12), 

plot, 

true 


); 


注意 ， 我 们 Subplot1 添 加 码 值 时 是 2 (方法 add() 的 第 二 个 参数 ) ， 而 subplot1 添 加 
的 是 1 呢 ? 因为 这 控制 着 分 配给 各 个 图 区 的 空间 大 小 。 


子 图 区 的 CategoryPlot 实 例 对 象 将 它们 的 X 轴 设置 为 null。 例 如 在 演示 的 实例 中 ， 代 
码 如 下 : 


CategoryDataset dataseti = createDataset1(); 

NumberAxis rangeAxisi = new NumberAxis("Value"); 
rangeAxis1.setStandardTickUnits(NumberAxis.createIntegerTickUnit 
S()); 

LineAndShapeRenderer rendereri = new LineAndShapeRenderer (); 
renderer1.setBaseToolTipGenerator(new StandardCategoryToolTipGen 
erator()); 

CategoryPlot subploti = new CategoryPlot(dataseti, null, rangeAx 
isi, rendereri); 

subplot1.setDomainGridlinesVisible(true); 

CategoryDataset dataset2 = createDataset2(); 

NumberAxis rangeAxis2 = new NumberAxis("Value"); 
rangeAxis2.setStandardTickUnits(NumberAxis.createIntegerTickUnit 
S()); 

BarRenderer renderer2 = new BarRenderer(); 
renderer2.setBaseToolTipGenerator(new StandardCategoryToolTipGen 
erator()); 

CategoryPlot subplot2 = new CategoryPlot(dataset2, null, rangeAx 
is2, renderer2); 

subplot2.setDomainGridlinesVisible(true) ; 


14.3 组 合 Y 种 类 图 区 


14.3.1 概述 


一 个 组 合 Y 种 类 图 区 就 是 一 个 图 区 显示 两 个 或 两 个 以 上 的 子 图 区 (CategoryPlot 实 
例 ) ， 共 享 Y 轴 。 如 果 14.2. 
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Class 1 Class 2 
图 14.2 组 合 Y 种 类 图 区 
该 图 表 可 以 水 平 显 示 也 可 以 重 直 显示 (本 例 是 重 直 显示 ) 。 





14.3.2 构建 图 表 


实例 演示 了 如 何 创 建 该 类 型 图 表 。 关 键 的 步骤 是 创建 一 个 实例 ， 然 后 添加 两 个 子 图 
区 : 


ValueAxis rangeAxis = new NumberAxis("Value"); 


CombinedRangeCategoryPlot plot = new 
CombinedRangeCategoryPlot(rangeAxis); plot.add(subplot1, 3); 
plot.add(subplot2, 2); JFreeChart result = new JFreeChart("Combined Range 
Category Plot Demo", new Font("SansSerif", Font.BOLD, 12), plot, true); 


注意 添加 的 子 图 区 subplot1 什 么 码 值 是 3 而 子 图 区 subplot2 码 值 是 2 呢 。 这 是 因为 该 
值 控制 这 两 个 子 图 区 分 配 的 空间 大 小 。 


子 图 区 是 CategoryPlot 实 例 ， 将 Y 轴 设置 为 hull。 例 如 ， 在 本 实例 演示 的 代码 如 下 : 


CategoryDataset dataset1 = createDataset1(); CategoryAxis domainAxis1 = new 
CategoryAxis("Class 1"); 
domainAxis1.setCategoryLabelPositions(CategoryLabelPositions.UP 45); 
domainAxis1.setWMaxCategoryLabelWidthRatio(5.0f); LineAndShapeRenderer 
renderer1 = new LineAndShapeRenderer(); 

renderer1.setBase ToolTipGenerator(new StandardCategory Tool TipGenerator()); 
CategoryPlot subplot1 = new CategoryPlot(dataset1, domainAxis1, null, 
renderer1); subplot1.setDomainGridlinesVisible(true); CategoryDataset dataset2 = 
createDataset2(); CategoryAxis domainAxis2 = new CategoryAxis("Class 2"); 
domainAxis2.setCategoryLabelPositions(CategoryLabelPositions.UP 45); 
domainAxis2.setMaxCategoryLabelWidthRatio(5.0f); BarRenderer renderer2 = 
new BarRenderer(); renderer2.setBase ToolTipGenerator(new 

StandardCategory ToolTipGenerator()); CategoryPlot subplot2 = new 
CategoryPlot(dataset2, domainAxis2, null, renderer2); 
subplot2.setDomainGridlinesVisible(true); `` 


14.4 组 合 X-XY 图 区 


14.4.1 概述 


组 合 X-XY 图 区 就 是 一 个 图 区 显示 两 个 或 者 多 个 子 图 区 (XYPlot 实 例 ) ， 共 享 一 个 X 
轴 。 每 一 个 子 图 区 维护 自己 的 Y 轴 。 如 下 图 14.3 所 示 . 
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图 14.3 组 合 X-XY 图 区 (参见 : CombinedXYPlotDemo5 java ) 
图 区 可 能 水 平 显示 也 可 能 垂直 显示 〈 本 例子 中 垂直 显示 ) 。 


14.4.2 构建 图 表 


CombinedXYPlotDemo5.java 实 例 演示 了 如 何 创建 该 类 型 的 图 表 。 关 键 的 步骤 是 创 
建 一 个 实例 CombinedDomainXYPlot， 并 在 该 实例 上 添加 两 个 子 图 区 : 


CombinedDomainXYPlot plot = new CombinedDomainXYPlot(new NumberA 
xis("Domain")); 
plot.setGap(10.0); 
plot.add(subplot1, 1); 
plot.add(subplot2, 1); 
plot.setOrientation(PlotOrientation.VERTICAL); 
return new JFreeChart( 
"CombinedDomainXYPlot Demo", 
JFreeChart.DEFAULT_TITLE_FONT, plot, true 


); 


注意 两 个 图 区 的 码 值 为 什么 都 是 1 呢 ? 因为 该 数值 控制 着 每 个 图 区 分 配 的 空间 大 
小 o 


子 图 区 是 XYPlot 实 例 ， 将 自己 的 X 轴 设置 为 null。 例如， 下 面 的 代码 演示 了 这 个 特 
RE: 


XYDataset datal = createDataseti(); 

XYItemRenderer renderer1 = new StandardXYItemRenderer(); 
NumberAxis rangeAxisi = new NumberAxis("Range 1"); 

XYPlot subploti = new XYPlot(data1, null, rangeAxisi, renderer1) 


£ 

subplot1.setRangeAxisLocation(AxisLocation.BOTTOM OR LEFT); 
XYTextAnnotation annotation = new XYTextAnnotation("Hello!", 50. 
©, 10000.0); 

annotation.setFont(new Font("SansSerif", Font.PLAIN, 9)); 
annotation.setRotationAngle(Math.PI / 4.0); 
subplot1.addAnnotation(annotation); 

// create subplot 2... 

XYDataset data2 = createDataset2(); 

XYItemRenderer renderer2 = new StandardXYItemRenderer(); 
NumberAxis rangeAxis2 = new NumberAxis("Range 2"); 
rangeAxis2.setAutoRangeIncludesZero( false); 

XYPlot subplot2 = new XYPlot(data2, null, rangeAxis2, renderer2) 


| 
subplot2.setRangeAxisLocation(AxisLocation.TOP OR LEFT); 


14.5 组 合 Y-XY 图 区 


14.5.1 概述 


组 合 Y-XY 图 区 就 是 一 个 图 区 显示 两 个 或 者 多 个 子 图 区 (XYPlot 实 例 ) ， 共 享 一 个 Y 
轴 。 每 一 个 子 图 区 维护 自己 的 X 轴 。 如 下 图 14.4 所 示 . 
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图 14.4 组 合 Y-XY 图 区 (参见 : CombinedXYPlotDemo5.java ) 
图 区 可 能 水 平 显示 也 可 能 垂直 显示 〈 本 例子 中 垂直 显示 ) 。 





14.5.2 构建 图 表 


CombinedXYPIlotDemo2java 实 例 演 示 了 如 何 创 建 该 类 型 的 图 表 。 关 键 的 步骤 是 创 
建 一 个 实例 CombinedRangeXYPlot， 并 在 该 实例 上 添加 两 个 子 图 区 : 


// create the plot... 
CombinedRangeXYPlot plot = new CombinedRangeXYPlot(new NumberAxi 
s("Value")); 
plot.add(xyplot, 1); 
plot.add(xyplot © , 1); 
return new JFreeChart( 
"Combined (Range) XY Plot", 
JFreeChart.DEFAULT_TITLE_FONT, plot, true 
); 


注意 两 个 图 区 的 码 值 为 什么 都 是 1 呢 ? 因为 该 数值 控制 着 每 个 图 区 分 配 的 空间 大 
小 o 


子 图 区 是 XYPlot 实 例 ， 将 自己 的 X 轴 设置 为 null。 例 如 ， 下 面 的 代码 演示 了 这 个 特 
RE: 


IntervalxXYDataset intervalxydataset = createDataset1(); 
XYBarRenderer xybarrenderer = new XYBarRenderer(0.2); 
xybarrenderer.setBaseToolTipGenerator(new StandardXYToolTipGener 
ator ( 

"{O}: ({1}, {2})", new SimpleDateFormat ("d-MMM-yyyy"), 

new DecimalFormat("0,000.0"))); 
XYPlot xyplot = new XYPlot(intervalxydataset, new DateAxis("Date 


NOG 
null, xybarrenderer); 
XYDataset xydataset = createDataset2(); 
StandardXYItemRenderer standardxyitemrenderer = new StandardXYIt 
emRenderer(); 
standardxyitemrenderer 
.setBaseToolTipGenerator(new StandardxXYToolTipGenerator ( 
"{O}: ({1}, {2})", new SimpleDateFormat ("d-MMM-yyyy"), 
new DecimalFormat("0,000.0"))); 
XYPlot xyplot 0 = new XYPlot(xydataset, new DateAxis("Date"), n 
ull, 
standardxyitemrenderer ); 


15 442 7% 4e JDBC(Dataset And JDBC) 


15.1 简介 
本 章节 ， 主 要 讲述 使 用 JDBC 从 数据 库 表 中 获得 数据 的 几 种 数据 源 方法 : 
e JDBCPieDataset 


e JDBCCategoryDataset 
e JDBCXY Dataset 


15.2 关于 JDBC 


JDBC (Java Data Base Connectivity,java 数 据 库 连接 ) 是 一 种 用 于 执行 SQL 语 句 
的 Java API， 可 以 为 多 种 关系 数据 库 提 供 统一 访问 ， 它 由 一 组 用 Java 语 言 编写 的 类 
和 接口 组 成 。JDBC 提 供 了 一 种 基准 ， 据 此 可 以 构建 更 高 级 的 工具 和 接口 ， 使 数据 
库 开发 人 员 能 够 编写 数据 库 应 用 程序 。 


15.3 样本 数据 

我 们 再 看 一 下 实际 运行 中 的 JDBC 数 据 源 。 我 们 需要 在 一 个 测试 数据 库 中 创建 一 些 
样本 数据 。 

下 面 列 出 了 创建 人 饼 图 、 直 方 条 形 图 和 时 序 图 的 样本 数据 。 

创建 饼 图 可 以 使 用 下 面 数据 (在 表 中 称谓 饼 数 据 ) 


CATEGORY VALUE 
London 54.3 
New York 43.4 
Paris 17.9 


同样 ， 直 方 条 形 图 使 用 下 面 数据 创建 (在 表 中 称谓 种 类 数据 ) 


CATEGORY SERIES1 SERIES2 SERIES3 
London 54.3 32.1 53.4 
New York 43.4 54.3 15-2 
Paris 17.9 34.8 37.1 


最 后 ， 时 序 图 表 的 使 用 的 数据 如 下 (在 表 中 称谓 xy 数 据 ) 


x SERIES1 SERIES2 SERIES3 
1-Aug-2002 54.3 324 53.4 
2-Aug-2002 43.4 54.3 75.2 
3-Aug-2002 39.6 55.9 37.1 
4-Aug-2002 35.4 55.2 27.5 
5-Aug-2002 33.9 49.8 pe 
6-Aug-2002 35.2 48.4 7 
7-Aug-2002 38.9 49.7 15.3 
8-Aug-2002 36.3 44.4 2A 
9-Aug-2002 31.0 46.3 11.0 


我 们 可 以 创建 一 个 测 斌 数据库， 包含 上 面 的 表 。 这 里 我 们 创建 一 个 jfreechartdb 数 据 
库 O 


在 下 一 章节 里 ， 我 们 使 用 PostgreSQL 创 建 数据 。 如 果 使 用 的 是 不 同 的 数据 库 系 
统 ， 我 们 需要 对 这 个 过 程 做 一 些 修 改 。 


15.4 PostgreSQL 


15.4.1 关于 PostgreSQL 


PostgreSQL 是 一 个 非常 强大 的 面向 关系 的 数据 库 服务 系统 ， 是 一 个 开源 的 分 布 式 
系统 。 我 们 可 以 从 下 面 链接 获得 更 多 的 信息 : 


http://www.postgresql.org 


注意 尽管 PostgreSQL 是 开源 的 ， 但 它 具 有 其 他 大 型 商业 关系 数据 库 系统 的 大 部 分 
特征 。 这 里 鼓励 你 安装 ， 并 使 用 它 。 


15.4.2 创建 一 个 新 的 数据 库 
首先 ， 登 录 数 据 库 管 理 系统 ， 创 建 一 个 名 为 jfreechartdb 的 数据 库 。 


CREATE DATABASE jfreechartdb; 


其 次 ， 创 建 一 个 jfreechart 用 户 : 


CREATE USER jfreechart WITH PASSWORD ‘password’; 


JDBC 可 以 使 用 这 个 用 户 名 和 密码 进行 数据 库 的 连接 。 
15.4.3 创建 饼 图 数据 
创建 饼 图 数据 库 表 : 


CREATE TABLE piedatal ( 
category VARCHAR(32), 
value FLOAT 

); 


加 入 样本 数据 : 


INSERT INTO piedatai VALUES (‘’London’, 54.3); 
INSERT INTO piedatai VALUES (‘New York’, 43.4); 
INSERT INTO piedatai VALUES (’Paris’, 17.9); 


15.4.4 创建 种 类 图 表 数 据 


创建 种 类 图 数据 库 表 : 


CREATE TABLE categorydata1 ( 
category VARCHAR(32), 
seriesi FLOAT, 
series2 FLOAT, 
series3 FLOAT 


); 


加 入 样本 数据 : 


INSERT INTO categorydatai VALUES (’London’, 54.3, 32.1, 53.4); 
INSERT INTO categorydatai VALUES (’New York’, 43.4, 54.3, 75.2); 
INSERT INTO categorydatai VALUES (’Paris’, 17.9, 34.8, 37.1); 


15.4.5 创建 XY 图 表 数 据 
创建 种 类 图 数据 库 表 : 


CREATE TABLE xydatal ( 
date DATE, 
seriesi FLOAT, 
series2 FLOAT, 
series3 FLOAT 


); 


加 入 样本 数据 : 
INSERT INTO xydata1 VALUES (’1-Aug-2002’, 54.3, 32.1, 53.4); 
INSERT INTO xydatai1 VALUES (’2-Aug-2002’, 43.4, 54.3, 75.2); 
INSERT INTO xydatail VALUES (’3-Aug-2002’, 39.6, 55.9, 37.1); 
INSERT INTO xydatail VALUES (’4-Aug-2002’, 35.4, 55.2, 27.5); 
INSERT INTO xydatai1 VALUES (’5-Aug-2002’, 33.9, 49.8, 22.3); 
INSERT INTO xydatail VALUES (’6-Aug-2002’, 35.2, 48.4, 17.7); 
INSERT INTO xydatai1 VALUES (’7-Aug-2002’, 38.9, 49.7, 15.3); 
INSERT INTO xydatai1 VALUES (’8-Aug-2002’, 36.3, 44.4, 12.1); 
INSERT INTO xydatail VALUES (’9-Aug-2002’, 31.0, 46.3, 11.0); 


15.4.6 设置 权限 


最 后 一 步 是 给 样本 数据 授 一 读 的 权限 给 新 用 户 jfreechart : 


GRANT SELECT ON piedatai TO jfreechart; 
GRANT SELECT ON categorydatai TO jfreechart; 
GRANT SELECT ON xydatai1 TO jfreechart; 


15.5 JDBC 驱 动 


为 了 使 用 JDBC 访 问 样本 数据 ， 我 们 需要 获得 数据 库 的 JDBC 了 驱动 。 对 于 
PostgreSQL， 可 以 从 下 面 的 连接 下 载 : 

http://jdbc.postgresql.org 

为 了 使 用 这 个 驱动 ， 确 保 这 个 驱动 jar 文 件 加 到 classpath 中 。 


15.6 应 用 演示 


15.6.1 JDBC 饼 图 演示 


JDBC 人 饼 图 ane 并 图 数据 表 的 数据 产生 饼 图 。 该 数据 是 由 我 们 配置 


据 库 中 获得 的 
读数 据 的 代码 在 方法 readData() 中 : 


private PieDataset readData() { 
JDBCPieDataset data = null; 


String url = "jdbc:postgresql://nomad/jfreechartdb"; 


Connection con; 

try { 
Class.forName("org.postgresql.Driver"); 

} catch (ClassNotFoundException e) { 
System.err.print("ClassNotFoundException: "); 
System.err.println(e.getMessage()); 


} 
try { 
con = DriverManager.getConnection(url, "jfreechart", 
ssword"); 


data = new JDBCPieDataset(con); 

String sql = "SELECT * FROM PIEDATA1;"; 
data.executeQuery(sql); 

con.close(); 

} catch (SQLException e) { 
System.err.print("SQLException: "); 
System.err.println(e.getMessage()); 

} catch (Exception e) { 
System.err.print("Exception: "); 
System.err.println(e.getMessage()); 


return data; 


在 代码 中 需要 注意 的 事项 : 
o Url 是 连接 数据 库 的 链接 字符 串 。 


的 数 


"pa 


o 返回 的 查询 数据 使 用 了 JDBCPieDataset 类 对 象 进行 了 封装 。 详 细 内 容 见 文 


档 。 


15.6.2 JDBC 种 类 图 演示 


JDBC 种 类 图 应 用 使 用 种 类 数据 产生 了 一 个 条 形 直方 图 。 代 码 类 似 于 JDBC 饼 图 代 


码 。 但 我 们 需要 使 用 JDBCCategoryDataset 类 类 封装 格式 化 数据 。 


15.6.3 JDBC XY 图 演示 


JDBC XY 图 应 用 使 用 XY 数 据 产 生 了 一 个 时 序 图 。 代 码 类 似 于 JDBC 饼 图 代码 。 但 我 
们 需要 使 用 JDBCXYDataset 类 类 封装 格式 化 数据 。 


16 导出 图 表 为 PDF 格式 


16.1 简介 


在 本 章节 中 ， 我 们 讲述 如 何 将 一 个 JFreeChart 生 成 图 表 转 换 成 PDF 格式 文件 。 主 要 
使 用 的 工具 是 IText。 随 着 讲述 ， 在 后 面 的 章节 中 用 一 个 简单 的 实例 说 明 创 建 PDF 文 
件 的 过 程 ， 该 PDF 文件 包含 了 一 个 简单 的 图 表 。 生 成 的 文件 ， 可 以 使 用 Acrobat 阅 
读 器 来 阅读 ， 也 可 以 使 用 支持 PDF 文件 阅读 的 阅读 器 来 阅读 。 


16.2 什么 是 Acrobat PDF 


Acrobat PDF 是 一 款 非 常 流行 的 电子 文档 阅读 器 。 可 实现 不 同 的 硬件 平台 和 软件 应 
用 程序 之 间 的 信息 共享 ,不 受 软 件 版 本 的 不 同和 安装 的 字体 的 影响 。PDF 可 以 使 用 
Adobe 提供 的 一 个 免费 工具 Acrodbat Reader 来 创建 。Acrodbat Reader 在 终端 用 户 
各 种 平台 上 是 有 效 的 ， 包 括 GNU/Linux,Windows,Unix,Machintosh 等 。 


如 果 你 的 系统 上 没有 安装 Acrodbat Reader， 可 以 到 下 面 链接 去 下 载 : 


http://www.adobe.com/products/acrobat/readstep.html 


16.3 1Text 


iText 是 一 个 能 够 快速 产生 PDF 文件 的 java 类 库 。iText 的 主页 下 载 地 址 是 : 
http://www.lowagie.com/iText 


截止 写本 文 的 时 间 ， 最 新 的 版 本 是 2.0.6 


16.4 Graphics2D 


JFreeChart 使 用 iText 工 具 是 非常 容易 的 事情 ， 因 为 iText 提 供 了 Graphics2D 的 实现 。 
在 我 们 说 明 实 例 应 用 之 前 ， 我 们 先 回顾 一 下 Graphics2D 的 类 。 


Java.awt. Graphics2D 类 ， 标 准 java2D API 的 一 部 分 。 定 义 了 在 二 维 空间 中 大 量 画 
文本 和 图 形 的 方法 。Graphics2D 部 分 子 类 处 理 全 部 的 转化 细节 ， 从 输出 (文本 和 图 
形 ) 到 具体 设置 的 映射 转化 。 


JFreeChart 画 图 表 时 ， 仅 仅 使 用 Graphics2D 定 义 的 方法 。 这 就 意味 着 JFreeChart 可 
以 将 图 表 输 出 到 Graphics2D 子 类 支持 的 任何 设备 。 









JFreeChart 
+draw(Graphics2D) 


图 16.2 JFreeChart 画 图 的 方法 


iText 工 具 融 入 了 PdfGraphics2D 的 一 个 类 ， 这 就 意味 着 iText 使 用 Graphics2D 类 定义 
的 方法 产生 PDF 内 容 。 并 且 正 如 你 在 后 面 的 章节 中 看 到 的 ， 在 PDF 格式 中 产生 图 表 
会 变 的 非常 的 容易 。 


16.5 开始 导出 


为 了 完成 和 演示 应 用 实例 ， 我 们 需要 下 面 的 jar 文 件 : 


EIT 描述 
jfreechart-1.0.6.jar JFreeChart 类 库 
jcommon-1.0.9.jar Jcommon& 
itext-2.0.6.jar ltext 类 库 


首先 JFreeChart 包 括 两 个 jar 文 件 ， 其 次 iText 需 要 一 个 jar 文 件 。 


16.6 实例 应 用 
首先 ， 需 要 创建 一 个 图 表 ， 我 们 创建 一 个 时 序 图 ， 代 码 如 下 


XYDataset dataset = createDataset(); 
JFreeChart chart = ChartFactory.createTimeSeriesChart ( 
"Legal & General Unit Trust Prices", 
"Date" y 
"Price Per Unit", 
dataset, 
true, 
true, 
false 


); 


这 里 没有 任何 的 特殊 代码 事实 上 ， 我 们 可 以 使 用 创建 JFreeChart 的 其 他 对 象 替 
代 上 面 的 代码 。 


一 步 ， 我 们 将 在 一 个 PDF 文件 中 保存 一 个 图 表 的 副本 : 


File fileName = new File(System.getProperty("user.home") + "/jfr 
eecharti.pdf"); 
saveChartAsPDF(fileName, chart, 400, 300, new DefaultFontMapper ( 


) ) ， 


下 面 有 一 些 需 要 注意 的 问题 : 


首先 ，PDF 文 件 名 称 是 硬 编码 完成 的 ， 不 能 修改 。 主 要 是 在 演示 中 ， 减 少 代码 量 。 
在 实际 应 : 中 ， 我 们 需要 提供 一 些 让 用 户 指 定 文件 名 称 与 路 径 的 方式 ， 比 如 弹出 一 
个 文件 选择 对 话 框 。 


其 次 > SaveChartAsPDF() 方 法 还 未 实现 。 为 了 创建 这 个 方法 ， 我 们 先 创 建 另 一 个 更 
通用 的 writeChartAsPDF(). 方 法 。 该 方法 执行 saveChartAsPDF() 方 法 需要 的 全 部 工 
作 。 但 该 方法 的 输入 参数 是 一 个 文件 输出 流 而 不 是 一 个 文件 ， 代 码 如 下 


public static void writeChartAsPDF(OutputStream out, JFreeChart 
chart, 
int width, int height, FontMapper mapper) throws IOException { 
Rectangle pagesize = new Rectangle(width, height); 
Document document = new Document(pagesize, 50, 50, 50, 50); 


try { 
Pdfwriter writer = PdfWriter.getInstance(document, out); 


document .addAuthor ("JFreeChart"); 

document .addSubject("Demonstration"); 

document .open(); 

PdfContentByte cb = writer.getDirectContent(); 
PdfTemplate tp = cbh.createTemplate(width, height); 
Graphics2D g2 = tp.createGraphics(width, height, mapper) 


Rectangle2D r2D = new Rectangle2D.Double(0, ©, width, he 
ight); 
chart.draw(g2, r2D); 
g2.dispose(); 
cb.addTemplate(tp, 0, 0); 
} catch (DocumentException de) { 
System.err.println(de.getMessage()); 


} 


document.close(); 


在 上 面 代码 的 方法 里 面 ， 我 们 看 到 一 些 创 建 和 代码 iText 文 档 的 代码 ， 从 文档 中 获得 
了 一 个 Graphics2D 实 例 ， 使 用 Graphics2D 对 象 画 出 这 个 图 表 ， 并 关闭 了 这 个 文 
档 。 


同时 我 们 也 注意 到 方法 的 一 个 参数 是 FontMapper 对 象 。iText 使 用 FontMapper 接 口 
将 java 字 体 对 象 映 射 成 基本 的 字体 对 象 。DefaultFontMapper 类 预先 默认 映射 为 java 
本 地 化 字体 。 如 果 你 希望 用 这 些 字体 ， 使 用 DefaultFontMapper 构 建 缺 省 的 对 象 即 
可 ， 如 果 你 相 使 用 其 他 的 字体 (例如 ， 支 持 一 个 特殊 的 字符 集 ) ， 那 么 我 们 需要 做 
一 些 额外 的 工作 。 本 章 后 面 将 有 介绍 。 


在 writeChartAsPDF() 方 法 的 实现 里 面 ， 我 们 创建 了 一 个 自 定义 页 面 尺 寸 大 小 (匹配 
字符 的 需要 尺寸 ) 的 PDF 文档 。 我 们 提前 设置 了 改变 了 字符 的 尺寸 、 位 置 并 且 在 
PDF 文档 中 画 出 多 个 字符 ， 以 适应 不 同 的 页 面 尺 寸 。 

现在 我 们 将 使 用 saveChartAsPDF() 方 法 很 容 多 的 实现 了 将 一 个 PDF 数据 发 送 到 一 个 
数据 流 上 “。 建 化 了 创建 文件 输出 流 的 过 程 ， 并 且 将 该 对 象 传 给 了 writeChartAsPDF() 
方法 。 代 码 如 下 : 


public static void saveChartAsPDF(File file, JFreeChart chart, i 
nt width, 
int height, FontMapper mapper) throws IOException { 
OutputStream out = new BufferedOutputStream(new FileOutputSt 
ream(file)); 
writeChartAsPDF(out, chart, width, height, mapper); 
out.close(); 


上 面 的 每 一 步 代 码 都 是 必须 的 。 上 面 的 代码 组 合成 全 部 的 代码 如 下 (整个 工程 的 代 
码 都 在 这 里 ， 以 便 我 们 可 以 看 到 所 有 的 声明 和 内 容 ) : 


package demo; 
import java.awt.Graphics2D; 
import java.awt.geom.Rectangle2D; 
import java.io.BufferedOutputStream; 
import java.io.File; 
import java.io.FileOutputStream; 
import java.io.I0OException; 
import java.io.OutputStream; 
import java.text.SimpleDateFormat; 
import org.jfree.chart.ChartFactory; 
import org.jfree.chart.JFreeChart; 
import org.jfree.chart.axis.DateAxis; 
import org.jfree.chart.plot.XYPlot; 
import org.jfree.chart.renderer.xy.XYLineAndShapeRenderer ; 
import org.jfree.data.time.Month; 
import org.jfree.data.time.TimeSeries; 
import org.jfree.data.time.TimeSeriesCollection; 
import org.jfree.data.xy.XYDataset; 
import com. lowagie.text.Document; 
import com. lowagie.text.DocumentException; 
import com. lowagie.text.Rectangle; 
import com. lowagie.text.pdf.DefaultFontMapper ; 
import com. lowagie.text.pdf.FontMapper; 
import com. lowagie.text.pdf.PdfContentByte; 
import com. lowagie.text.pdf.PdfTemplate; 
import com. lowagie.text.pdf.Pdfwriter; 
Vis 
* A simple demonstration showing how to write a chart to PDF for 
mat using 
* JFreeChart and iText. 
* &1t;P&gt; 
* You can download iText from http://www. lowagie.com/iText. 
ay 
public class PDFExportDemo1 { 

[rss 

* Saves a chart to a PDF file. 


* 


* @param file 


the file. 

@param chart 

the chart. 

@param width 

the chart width. 
@param height 
the chart height. 


~ FF OHO 


2 
public static void saveChartAsPDF(File file, JFreeChart char 
t, int width, 
int height, FontMapper mapper) throws IOException { 
OutputStream out = new BufferedOutputStream(new FileOutp 
utStream(file)); 
writeChartAsPDF(out, chart, width, height, mapper); 
out.close(); 


+ 
+ 


Writes a chart to an output stream in PDF format. 


@param out 

the output stream. 
@param chart 

the chart. 

@param width 

the chart width. 
@param height 

the chart height. 


+ 4 FF FF F N” 


E 

public static void writeChartAsPDF(OutputStream out, JFreeCh 
art chart, 

int width, int height, FontMapper mapper) throws IOException 


Rectangle pagesize = new Rectangle(width, height); 
Document document = new Document(pagesize, 50, 50, 50, 5 


try { 
Pdfwriter writer = PdfWriter.getInstance(document, o 


ut); 

document .addAuthor ("JFreeChart"); 

document .addSubject("Demonstration"); 

document .open(); 

PdfContentByte cb = writer.getDirectContent(); 

PdfTemplate tp = cbh.createTemplate(width, height); 

Graphics2D g2 = tp.createGraphics(width, height, map 
per); 

Rectangle2D r2D = new Rectangle2D.Double(0, ©, width 
, height); 

chart.draw(g2, r2D); 

g2.dispose(); 

cb.addTemplate(tp, 0, 0); 

} catch (DocumentException de) { 
System.err.printin(de.getMessage()); 


} 


document .close(); 
} 
[pte 
* Creates a dataset, consisting of two series of monthly dat 
k * 
ae * 
* @return the dataset. 
ay 
public static XYDataset createDataset() { 
TimeSeries s1 = new TimeSeries("L&G European Index Trust 
", Month.class); 
si.add(new Month(2, 2001), 181.8); 
si.add(new Month(3, 2001), 167.3); 
s1.add(new Month(4, 2001), 153.8); 
si.add(new Month(5, 2001), 167.6); 
si.add(new Month(6, 2001), 158.8); 
S1.add(new Month(7, 2001), 148.3); 
si.add(new Month(8, 2001), 153.9); 
si.add(new Month(9, 2001), 142.7); 
si.add(new Month(10, 2001), 123.2); 
si.add(new Month(11, 2001), 131.8); 
si.add(new Month(12, 2001), 139.6); 
si.add(new Month(1, 2002), 142.9); 
S1.add(new Month(2, 2002), 138.7); 
s1.add(new Month(3, 2002), 137.3); 
si.add(new Month(4, 2002), 143.9); 
si.add(new Month(5, 2002), 139.8); 
si.add(new Month(6, 2002), 137.0); 
si.add(new Month(7, 2002), 132.8); 
TimeSeries s2 = new TimeSeries("L&G UK Index Trust", Mon 
th.class); 
s2.add(new Month(2, 2001), 129.6); 
s2.add(new Month(3, 2001), 123.2); 
s2.add(new Month(4, 2001), 117.2); 
s2.add(new Month(5, 2001), 124.1); 
s2.add(new Month(6, 2001), 122.6); 
s2.add(new Month(7, 2001), 119.2); 
s2.add(new Month(8, 2001), 116.5); 
s2.add(new Month(9, 2001), 112.7); 
s2.add(new Month(10, 2001), 101.5); 
s2.add(new Month(11, 2001), 106.1); 
s2.add(new Month(12, 2001), 110.3); 
s2.add(new Month(1, 2002), 111.7); 
s2.add(new Month(2, 2002), 111.0); 
s2.add(new Month(3, 2002), 109.6); 
s2.add(new Month(4, 2002), 113.2); 
s2.add(new Month(5, 2002), 111.6); 
s2.add(new Month(6, 2002), 108.8); 
s2.add(new Month(7, 2002), 101.6); 
TimeSeriesCollection dataset = new TimeSeriesCollection( 
); 


dataset .addSeries(s1); 


dataset.addSeries(s2); 
return dataset; 
} 
public static void main(String[] args) { 
try { 
// create a chart... 
XYDataset dataset = createDataset(); 
JFreeChart chart = ChartFactory.createTimeSeriesChar 
t( 

"Legal & General Unit Trust Prices", "Date", 

"Price Per Unit", dataset, true, true, false); 
// some additional chart customisation here... 
XYPlot plot = chart.getXYPlot(); 
XYLineAndShapeRenderer renderer = (XYLineAndShapeRen 

derer) plot 

.getRenderer(); 
renderer .setShapesVisible(true); 

DateAxis axis = (DateAxis) plot.getDomainAxis(); 

axis.setDateFormatOverride(new SimpleDateFormat ("MMM 
-yyyy")); 

// write the chart to a PDF file... 

File fileName = new File(System.getProperty("user.ho 
me") 

+ "/jfreechart1.pdf"); 
System.out.println(fileName.getPath()); 
saveChartAsPDF(fileName, chart, 400, 300, new Defaul 

tFontMapper()); 
} catch (IOException e) { 
System.out.println(e.getMessage()); 
} 


在 你 完成 和 运行 上 面 的 应 用 之 前 ， 记 得 修改 PDF 文件 的 名 称 以 满足 我 们 的 要 求 。 同 
时 前 面 16.5 节 提 到 的 jar 也 必须 在 我 们 的 classpath 中 。. 


16.7 查看 PDF 文件 


在 我 们 完成 上 面 实例 ， 运 行 实例 ， 会 产生 一 个 PDF 文档 。 我 们 可 以 使 用 一 个 PDF 浏 
览 器 (比如 AcrobatReader (或 者 其 他 支持 的 阅读 器 ，Gnome PDF Viewer) ) 查 
看 该 文件 ， 显 示 的 界面 如 下 图 16.3 
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A 16.3 JFreeChart 使 用 iText 生 成 的 PDF 文件 图 
大 部 分 的 PDF 阅读 器 都 提供 了 缩放 技术 ， 以 允许 我 们 更 进一步 浏览 我 们 的 图 表 。 


16.8 Unicode 字 符 问 题 


声明 : 由 于 本 人 对 自 字 符 集 了 解 不 深 ， 因 此 翻译 效果 比较 差 ， 忘 各 大 网 友 给 予 大 力 
支持 。 


在 我 们 关心 我 们 所 使 用 的 字体 字符 集 时 ， 在 JFreeChart 和 iText 中 使 用 Unicode 字 符 
集 是 没有 任何 问题 的 。 在 上 面 的 例子 中 我 们 需要 做 一 些 修 改 来 演示 如 何 做 到 这 些 。 


16.8.1 背景 


Java 使 用 同一 的 字符 集 译 码 成 文本 字符 串 。 这 种 译 码 对 每 个 字符 使 用 16 进 制 。 这 就 
意味 着 将 有 65，536 个 有 效 的 不 同 字 符 集 (在 Unicode 标 准 中 定义 了 大 约 38，000 个 
字符 ) 
我 们 可 以 在 JFreeChart 和 iText 中 使 用 这 些 字符 ,但 归于 一 条 : 那 就 是 只 要 我 们 使 用 的 
字体 ， 包 括 我 们 用 来 显示 的 文本 或 者 不 显示 的 ， 都 必须 定义 这 些 字符 。 许 多 字体 并 
cd 人 o 下面 的 网 站 含有 那些 的 确 支持 Unicode 的 字体 的 有 用 
信息 


o 


http://www.slovo.info/unifonts.htm 


我 们 可 以 成 功 的 提取 使 用 tahoma.ttf 字 体 。 实 际 上 ， 下 面 实例 中 我 们 将 使 用 该 字 

体 ，Tahoma 字 体 并 不 是 支持 Unicode 定 义 的 每 一 个 字符 。 因 此 ， 如 果 我 们 想 使 用 一 
种 特殊 的 字体 时 ， 就 得 必须 选 Unicode 中 一 种 相近 的 字体 来 代替 。 我 们 系统 上 都 安 
装 了 字体 Unicode MS (arialuni.ttf) 一 一 该 字体 完全 支持 Unicode 字 符 集 ， 尽 管 这 种 字 
体 的 定义 的 文件 特别 大 (大约 24M ) 





16.8.2 字体 、iText 和 Java 


iText 依 照 PDF 规 格 来 处 理 字体 ， 这 就 对 使 用 PDF 文件 具 入 的 字体 来 处 理 文 件 带 来 了 
非常 大 的 方便 性 ， 同 时 也 需要 自由 读 取 定义 文件 的 字体 。 

而 java 在 字体 类 中 汲取 了 部 分 字体 格式 的 大 部 分 细节 内 容 。 

在 iText 中 ， 为 支持 Graphics2D 的 实现 画图 功能 ， 实 现 从 Java 字 体 对 象 到 BaseFont 
对 象 的 映射 字体 对 象 是 非常 有 必要 的 。 这 就 是 FontMapper 接 口 所 扮演 的 角色 。 


如 果 我 们 使 用 缺 省 的 构建 器 构建 了 一 个 新 的 DefaultFontMapper 实 例 ， 那 么 总 会 带 
有 Java 规 格 定义 的 本 地 字体 映射 。 但 是 如 果 我 们 想 使 用 其 他 一 些 字 体 一 一 并 且 我 们 
必须 使 用 Unicode 之 外 的 字符 一 一 那么 我 们 需要 将 其 他 的 字符 映射 加 入 到 
DefaultFontMapper 对 象 中 。 


16.8.3 映射 第 三 方 的 字体 


这 里 我 们 决定 使 用 Tahoma 字 体 来 显示 标题 。 该 字体 的 定义 文件 (tahoma.ttf) 在 我 们 
系统 下 面 的 目录 下 可 以 找到 。 


/opt/sun-jdk-1.4.2.08/jre/lib/fonts 


现在 我 们 使 用 代码 说 明 ， 使 用 iText 创 建 FontMapper 对 象 来 使 用 Tahoma 字 体 : 


// 设 置 字体 
DefaultFontMapper mapper = new DefaultFontMapper(); 
mapper.insertDirectory("D:\\jrei1.5.0_10\\lib\\fonts"); 
DefaultFontMapper.BaseFontParameters pp = 

mapper .getBaseFontParameters("Tahoma"); 
if (pp!=null) { 

pp.encoding = BaseFont.IDENTITY_H; 
} 


现在 我 们 可 以 修改 创建 图 表 的 代码 ， 将 图 表 的 标题 使 用 该 字体 : 


TextTitle textTitle = chart.getTitle(); 

textTitle.setFont(new Font("Tahoma", Font.PLAIN, 20)); 

String text = "\u278A\u20A0\U20A1\U20A2\U20A3\U20A4\U20A5\U20A6\ 
u20A7 \uU20A8\uU20A9"; 

// String text = "hi"; 

Font font = new Font("Tahoma", Font.PLAIN, 12); 

TextTitle subtitle = new TextTitle(text, font); 
chart.addSubtitle(subtitle); 


副标题 的 输出 如 下 图 16.2 所 示 。 实 例 已 经 给 入 到 PDF 文 件 中 。 因 此 本 文 演示 的 该 小 
程序 很 好 的 展示 了 这 种 类 型 的 输出 ， 给 出 了 详细 的 步骤 指南 ， 便 于 我 们 正确 使 用 。 
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如 图 16.2 一 个 Unicode 副 标题 的 图 表 
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17 导出 图 表 为 SVG 格式 


17.1 简介 


在 本 章 里 ， 我 们 介绍 了 一 个 简单 实例 ， 实 例 演示 使 用 JFreeChart 和 Batik 工 具 (SVG 
开源 的 类 库 ) 如 何 将 图 表 寻 出 为 SVG 格式 。 


17.2 背景 


17.2.1 什么 是 SVG? 
SVG( 可 放 缩 的 矢量 图 形 ) 是 W3C(World Wide Web ConSor 一 tium 国 际 互联 网 标准 


组 织 ) 在 2000 年 8 月 制定 的 一 种 基于 XML 格式 的 新 的 二 维 矢量 图 形 格式 ， 也 是 规范 中 
的 网 络 矢量 图 形 标准 。 


17.2.2 Batik 


Batik 是 一 个 java 开 源 的 工具 包 ， 多 许 我 们 产生 SVG 内 容 。 可 以 从 下 面 的 链接 获得 有 
效 的 Batik : 


http://xml.apache.org/batik 
在 写本 文 之 前 ，Batik 最 新 的 版 本 是 1.7 


17.3 实例 代码 


17.3.1 JFreeChart 和 Batik 
JFreeChart 和 Batik 兼 容 性 非常 好 ， 因 为 : 


e 因为 JFreeChart 画 的 所 有 图 表 的 输出 都 是 使 用 的 Java 的 Graphics2D ; 
e Batik 具 体 实 现 了 Graphics2D 产 生 SVG 输 出 的 功能 (SVGGraphics2D) 。 


在 本 章节 ， 使 用 一 个 简单 的 实例 说 明 使 用 JFreeChart 和 Batik 实 现 SVG 的 输出 。 关 于 
该 实例 的 详细 技术 详 见 下 面 链 接 : 


http://xml.apache.org/batik/svggen.html 
17.3.2 开始 


首先 ， 我 们 需要 下 载 Batik 并 依照 网 站 的 指导 进行 安装 。 
确保 下 章节 的 例子 能 够 正常 运行 ， 需 要 将 下 面 的 jar 包 加 到 我 们 的 classpath : 


文件 描述 
jcommon-1.0.9.jar JFreeChart 的 通用 类 包 。 
jfreechart-1.0.6.jar JFreeChartay & & 
batik-awt-util.jar Batik 实 时 运行 文件 
batik-dom.jar Batik 实 时 运行 文件 
batik-svggen.jar Batik 实 时 运行 文件 
batik-util.jar Batik 实 时 运行 文件 


17.3.3 实例 应 用 


在 我 们 的 开发 环境 中 创建 一 个 工程 ， 并 且 将 上 节 列 出 的 jar 包 添加 到 工程 路 径 上 ， 并 
输入 下 面 代码 : 


package demo; 

import java.awt.geom.Rectangle2D; 

import java.io.File; 

import java.io.FileOutputStream; 

import java.io.I0Exception; 

import java.io.OutputStreamwriter; 

import java.io.Writer; 

import org.apache.batik.dom.GenericDOMImplementation; 
import org.apache.batik.svggen.SVGGraphics2D; 


import org.jfree.chart.ChartFactory; 
import org.jfree.chart.JFreeChart; 
import org.jfree.data.general.DefaultPieDataset; 
import org.w3c.dom.DOMImplementation; 
import org.w3c.dom.Document; 
Ce 
* A demonstration showing the export of a chart to SVG format. 
E 
public class SVGExportDemo { 
JA a 
* Starting point for the demo. 
* 
* @param args 
* ignored. 
ey 
public static void main(String[] args) throws IOException { 
// create a dataset... 
DefaultPieDataset data = new DefaultPieDataset(); 
data.setValue("Category 1", new Double(43.2)); 
data.setValue("Category 2", new Double(27.9)); 
data.setValue("Category 3", new Double(79.5)); 
// create a chart 
JFreeChart chart = ChartFactory.createPieChart("Sample P 
ie Chart", 
data, true, false, false); 
// THE FOLLOWING CODE BASED ON THE EXAMPLE IN THE BATIK 
DOCUMENTATION... 
// Get a DOMImplementation 
DOMImplementation domImpl = GenericDOMImplementation 
.getDOMImplementation(); 
// Create an instance of org.w3c.dom.Document 
Document document = domImpl.createDocument(null, "svg", 
null); 
// Create an instance of the SVG Generator 
SVGGraphics2D svgGenerator = new SVGGraphics2D(document ) 
| 
// set the precision to avoid a null pointer exception i 
n Batik 1.5 
svgGenerator.getGeneratorContext().setPrecision(6); 
// Ask the chart to render into the SVG Graphics2D imple 
mentation 
chart.draw(svgGenerator, new Rectangle2D.Double(0, 0, 40 
©, 300), null); 
// Finally, stream out SVG to a file using UTF-8 charact 
er to 
// byte encoding 
boolean useCSS = true; 
Writer out = new OutputStreamwriter(new FileOutputStream 
(new File( 
"test.svg")), "UTF-8"); 
svgGenerator.stream(out, useCSS); 





17.3.4 浏览 SVG 图 


Batik 类 库 内 包含 了 一 个 "Squiggle" 的 小 应 用 ， 我 们 可 以 使 用 该 工具 浏览 SVG 文 件 。 


我 们 可 以 使 用 下 面 命令 打开 : 


java -jar batik-squiggle.jar 


下 图 截屏 显示 了 上 述 代 码 创建 的 一 个 饼 图 的 界面 。 使 用 应 用 浏览 器 工具 ， 
浏览 器 中 进行 了 45 度 旋转 。 


Squiggle: test. svg Se 


File Edit View Processing Go Tools ? 
—) A F rA 
@is galne] 


局 Location: ffile:/C:Documents and Settings/mxq/s fij'test.svg v 














_ “> D" -C 
w: 590.43414 h: -135.05739 


如 图 17.1 SVG 截图 


将 图 表 在 


18 Applet 


18.1 简介 


18.1 简介 


局 限于 一 些 条 件 ， 在 Applet 中 使 用 JFreeChart 还 是 比较 容易 的 。 本 章节 对 Applet 进 
行 了 整体 的 介绍 ， 并 举例 说 明了 工作 过 程 。 这 样 对 我 们 开始 使 用 Applet 提 供 极 大 帮 


助 。 


= oþh FAAA: demo. åppletl. class TBR) 


Memory Usage 


o S H ! f i : 
15:38:42 15:38:43 15:38:44 15:38:45 15:38:46 15:38:47 
Time 


-一 Total — Free 


小 程序 已 启动 。 





图 18.1 JFreeChart 在 Applet 上 的 应 用 


图 18.1 显 示 了 一 个 使 用 JFreeChart 的 Applet 简 单 应 用 。 该 applet 可 以 通过 下 面 链接 


http://www.object-refinery.com/jfreechart/applet.html 


后 面 的 章节 有 全 部 的 代码 。 
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18.2 I] %& 


在 开发 applet 时 ， 考 虑 的 主要 问题 (与 JFreeChart 无 关 ) 是 : 


e 安全 约束 
e 字 节 码 文 件 大 小 


在 我 们 用 提供 的 有 效 资源 写 applets 时 ， 确 保 我 们 对 上 面 问 题 有 所 了 解 


18.2.1 浏览 器 支持 


绝 大 部 分 的 web 浏 览 器 均 对 最 新 版 本 的 JDK1.5 提 供 支 持 ， 因 此 使 用 JFreeChart 运 行 
applets 也 是 绝对 没有 任何 问题 的 (JFreeChart 可 以 运行 在 JDK1.3.1 版 本 或 以 上 版 
K) 。 尽 管 如 此 ， 很 大 一 部 分 用 户 还 是 使 用 一 个 浏览 器 的 一 一 微软 的 IE 浏览 器 
该 浏览 器 仅仅 支持 JDK1.1 版 本 ， 并 且 现 在 已 经 过 期 。 这 里 有 一 个 问题 是 ， 使 用 
JFreeChart 的 applet 应 用 在 微软 的 IE 上 是 不 能 默认 运行 的 。 这 就 必须 下 载 一 个 Java 
的 插件 ， 但 是 这 样 会 造成 很 多 不 必要 的 麻烦 和 困难 ， 最 终 的 问题 就 是 那些 开发 者 选 
择 写 applets 开 发 的 问题 ， 这 导致 开发 者 放弃 开发 applets， 而 选择 Java 

Servlets ( 见 下 一 章节 ) ° 








18.2.2 安全 


Applets 设 计时 ， 是 符合 java 安 全 规范 的 。 当 一 个 applet 运 行 在 我 们 的 web 浏 览 器 上 
时 ， 在 操作 上 是 受到 很 大 的 约束 的 。 例 如 ， 一 个 applet 典 型 的 是 不 能 读 写 本 地 文件 
系统 的 。 关 于 Java 安 全 机 制 的 描述 已 经 超出 了 本 章 的 范围 ， 但 是 我 们 必须 意识 到 
JFreeChart 的 一 些 功能 在 applets 上 是 不 能 运行 的 (例如 将 图 表 保 存 成 PNG 格 式 的 文 
件 ) ， 主 要 受 java 缺 省 的 安全 规则 约束 。 如 果 我 们 想 使 用 这 些 功 能 ， 那 么 我 们 需要 
认真 学 习 一 下 java 的 安全 机 制 的 更 多 细节 。 


18.2.3 代码 大 小 


最 后 一 个 文件 就 是 我 们 applet 运 行 时 需要 的 代码 量 问 题 。 在 我 们 运行 一 个 applet 之 
前 ， 代 码 被 下 载 到 本 地 客户 端 。 显 然 对 用 户 来 说 是 有 带宽 限制 的 ， 代 码 量 的 大 小 成 
了 关键 问题 。JFreeChart 代 码 的 jar 文 件 大 约 是 1M 堪 右 ， 对 JFreeChart 支 持 的 图 表 
来 说 ， 不 算 很 大 ， 但 对 使 用 modem 拨 号 上 网 的 用 户 来 说 ， 的 确 不 是 很 理想 的 。 同 时 
我 们 需要 将 JCommon 的 jar 包 (大约 290KB) 加 到 我 们 的 applet 上 。 考 虑 到 这 些 问 
题 ， 我 们 将 对 JFreeChart 进 行 重新 打包 ， 仅 仅 将 applet 需 要 的 类 文件 包含 进来 ， 从 
而 优化 代码 结构 。 


18.3 实例 应 用 


正如 在 简介 中 所 提 及 的 ， 使 用 JFreeChart 的 applet 可 以 在 下 面 链接 中 看 到 : 
http://www.object-refinery.com/jfreechart/applet.html 


运行 applet 应 用 时 ， 需 要 两 个 方面 狐 支 持 。 一 是 代码 方式 创建 applet， 二 是 HTML 文 
件 用 来 调用 applet。 


18.3.1 HTML 


因为 applet 需 要 引入 额外 的 jar 文 件 ， 所 以 在 HTML 中 使 用 applet 是 显得 非常 重要 。 
HTML applet 标 签 如 下 : 


<APPLET ARCHIVE="jfreechart-1.0.6-applet-demo. jar, 
jfreechart-1.0.6.jar, jcommon-1.0.9.jar" 
CODE="demo.applet.Appleti" width=640 height=260 
ALT="You should see an applet, not this text."> 
</APPLET> 


注意 这 里 有 三 个 jar 需 要 引入 ， 第 一 个 包含 了 applet 类 ， 另 外 两 个 jar 文 件 是 
JFreeChart 和 JCommon 类 库 。 我 们 需要 在 HTML 文 件 中 将 applet 标 签 引入 。 


18.3.2 BAG 


实例 applet 的 源 代码 见 下 (代码 中 我 们 使 用 了 很 少 的 applet 特 殊 的 代码 ， 仅 仅 扩展 
f JApplet) 


package demo; 

import java.awt.BasicStroke; 

import java.awt.Color; 

import java.awt.event.ActionEvent; 

import java.awt.event.ActionListener; 

import javax.swing.JApplet; 

import javax.swing.Timer; 

import org.jfree.chart.ChartPanel; 

import org.jfree.chart. JFreeChart; 

import org.jfree.chart.axis.DateAxis; 

import org.jfree.chart.axis.NumberAxis; 

import org.jfree.chart.plot.XYPlot; 

import org.jfree.chart.renderer.xy.XYItemRenderer ; 
import org.jfree.chart.renderer.xy.XYLineAndShapeRenderer ; 
import org.jfree.data.time.Millisecond; 

import org.jfree.data.time.TimeSeries; 

import org.jfree.data.time.TimeSeriesCollection; 

jf ire 


* A simple applet demo. 


wid 


public class Applet1 extends JApplet { 
/** Time series for total memory used. */ 
private TimeSeries total; 
/** Time series for free memory. */ 
private TimeSeries free; 


JAS 


* Creates a new instance. 


A 


public Applet1() { 


e than 


); 


// create two series that automatically discard data mor 


// 30 seconds old... 

this.total = new TimeSeries("Total", Millisecond.class); 
this.total.setMaximumItemAge (30000); 

this.free = new TimeSeries("Free", Millisecond.class); 
this.free.setMaximumItemAge( 30000) ; 

TimeSeriesCollection dataset = new TimeSeriesCollection( 


dataset.addSeries(total); 

dataset.addSeries(free); 

DateAxis domain = new DateAxis("Time"); 

NumberAxis range = new NumberAxis("Memory"); 
XYItemRenderer renderer = new XYLineAndShapeRenderer (tru 


e, false); 


r); 


nits()); 


} 


jeer 


XYPlot plot = new XYPlot(dataset, domain, range, rendere 


plot .setBackgroundPaint(Color.lightGray); 

plot .setDomainGridlinePaint(Color.white); 

plot .setRangeGridlinePaint(Color.white); 
renderer.setSeriesPaint(0, Color.red); 
renderer.setSeriesPaint(1, Color.green); 
renderer.setSeriesStroke(0, new BasicStroke(1.5f)); 
renderer.setSeriesStroke(1, new BasicStroke(1.5f)); 
domain. setAutoRange(true); 
domain.setLowerMargin(0.0); 

domain. setUpperMargin(0.0); 
domain.setTickLabelsVisible(true); 
range.setStandardTickUnits(NumberAxis.createIntegerTickU 


JFreeChart chart = new JFreeChart("Memory Usage", 
JFreeChart .DEFAULT_TITLE_FONT, plot, true); 
chart.setBackgroundPaint(Color.white) ; 

ChartPanel chartPanel = new ChartPanel(chart); 
chartPanel.setPopupMenu(null); 
getContentPane().add(chartPanel) ; 

new Appleti.DataGenerator().start(); 


* Adds an observation to the ‘total memory’ time series. 


* 


* @param y 


* the total memory used. 

2 

private void addTotalobservation(double y) { 
total.add(new Millisecond(), y); 


} 

JESS 

* Adds an observation to the “free memory’ time series. 
* 

* @param y 

* the free memory. 

a 


private void addFreeObservation(double y) { 
free.add(new Millisecond(), y); 
} 


[frre 

* The data generator. 

oy 

class DataGenerator extends Timer implements ActionListener 


jf rte 

* Constructor. 

ay. 

DataGenerator() { 
super(100, null); 
addActionListener(this); 


* Adds a new free/total memory reading to the dataset. 


* @param event 

* the action event. 

ay 

public void actionPerformed(ActionEvent event) { 
long f = Runtime.getRuntime().freeMemory(); 
long t = Runtime.getRuntime().totalMemory(); 
addTotalObservation(t); 
addFreeObservation(f); 


19 Servlets 


19.1 介绍 


Java Servlet API 是 一 套 创 建 web 应 用 非常 流行 成 熟 的 技术 。 在 servlet 环 境 中 使 用 
JFreeChart 是 非常 合适 的 。 在 本 章节 中 ， 协 助 开 发 者 在 web 应 用 中 使 用 
JFreeChart。 本 章 所 有 的 实例 可 以 从 下 面 链 接 中 下 载 : 


http://www.object-refinery.com/jfreechart/premium/index.html 


下 载 的 文件 名 为 : jfreechart-1.0.6-demo.zip 〈 该 信息 是 收费 的 ) . 


19.2 编写 一 个 简单 的 Servlet 应 用 


ServletDemo1 类 实现 了 一 个 非常 简单 的 servlet， 该 servlet 返 回 了 一 个 PNG 图 3 
PNG 图 是 使 用 JFreeChart 生 成 的 直方 条 形 图 表 。 当 运行 该 程序 时 ，servlet 在 客户 端 
仅仅 显示 一 幅 图 片 ， 而 没有 任何 的 HTML 修 饰 ， 参 见 下 图 19.1。 


$ :1 1/servlet/Servl... TBR) 
WFO ARO SEW KEA IAG Raw ax 


Qa- O- DAO Pm kme ” 





地 址 0) E http: //localhost :8080/ j freechart!/servlet/Serviet|¥| 转 到 ”链接 > 





Bar Chart 


c4 








Category 
@S1@S28S30S48S5@S60S7—8s8smgsg 


a) 本 地 Intranet 








如 图 19.1 浏览 器 中 的 servlet 效 果 
我 们 以 这 种 方式 显示 图 片 ， 是 没有 特殊 意义 ， 仅 仅 是 为 了 : 


o 很 好 演 示 servlets 的 请 求 一 响应 交互 特征 ; 
o 作为 测试 实例 非常 有 用 ， 我 们 会 了 解 如 何 配置 一 个 服务 环境 ， 如 何 让 页 面 控件 
工作 。 


我 们 可 以 浏览 后 面 更 复杂 的 实例 ， 显 示 使 用 HMTL 表 单 如 何 请 求 不 同 的 图 表 ， 并 且 
将 产生 的 图 表 的 输出 植 入 到 HTML 中 。 下 面 是 基本 servlet 的 代码 © 


package demo; 

import java.io.IOException; 

import java.io.OutputStream; 

import javax.servlet.ServletException; 

import javax.servlet.http.HttpServlet; 

import javax.servlet.http.HttpServletRequest; 
import javax.servlet.http.HttpServletResponse; 


import org.jfree.chart.ChartFactory; 

import org.jfree.chart.ChartUtilities; 

import org.jfree.chart.JFreeChart; 

import org.jfree.chart.plot.PlotOrientation; 

import org.jfree.data.category.DefaultCategoryDataset; 

[fre 

* A basic servlet that returns a PNG image file generated by JFr 
eeChart. This 

* class is described in the JFreeChart Developer Guide in the "S 
ervlets" 


* chapter. 

=y 

public class ServletDemo1 extends HttpServlet { 
ffs 
* Creates a new demo. 
ey 


public ServletDemo1() { 
// nothing required 

} 

[ers 

Processes a GET request. 


+ 


@param request 
the request. 
@param response 
the response. 


@throws ServletException 

if there is a servlet related problem. 
@throws IOException 

if there is an I/O problem. 


~*~ FF F FF FF FF F HF F 


ay A 
public void doGet(HttpServletRequest request, HttpServletRes 
ponse response) 
throws ServletException, IOException { 
OutputStream out = response.getOutputStream(); 
try { 
DefaultCategoryDataset dataset = new DefaultCategory 
Dataset(); 

dataset.addValue(10.0, "Si", "C1"); 
dataset.addValue(4.0, "Si", "C2"); 
dataset.addValue(15.0, "Si", "C3"); 
dataset.addValue(14.0, "Si", "C4"); 
dataset.addValue(-5.0, "S2", "C1"); 
dataset.addValue(-7.0, "S2", "C2"); 
dataset.addValue(14.0, "S2", "C3"); 
dataset.addValue(-3.0, "S2", "C4"); 
dataset.addValue(6.0, "S3", "C1i"); 
dataset.addValue(17.0, "S3", "C2"); 
dataset.addValue(-12.0, "S3", "C3"); 
dataset.addValue(7.0, "S3", "C4"); 
dataset.addValue(7.0, "S4", "C1"); 
dataset.addValue(15.0, "S4", "C2"); 


dataset.addValue(11.0, "S4", "C3"); 
dataset.addValue(0.0, "S4", "C4"); 
dataset.addValue(-8.0, "S5", "C1"); 
dataset.addValue(-6.0, "S5", "C2"); 
dataset.addValue(10.0, "S5", "C3"); 
dataset.addValue(-9.0, "S5", "C4"); 
dataset.addValue(9.0, "S6", "C1"); 
dataset.addValue(8.0, "S6", "C2"); 
dataset.addValue(null, "S6", "C3"); 
dataset.addValue(6.0, "S6", "C4"); 
dataset.addValue(-10.0, "S7", "C1"); 
dataset.addValue(9.0, "S7", "C2"); 
dataset.addValue(7.0, "S7", "C3"); 
dataset.addValue(7.0, "S7", "C4"); 
dataset.addValue(11.0, "S8", "C1"); 
dataset.addValue(13.0, "S8", "C2"); 
dataset.addValue(9.0, "S8", "C3"); 
dataset.addValue(9.0, "S8", "C4"); 
dataset.addValue(-3.0, "S9", "C1"); 
dataset.addValue(7.0, "S9", "C2"); 
dataset.addValue(11.0, "S9", "C3"); 
dataset.addValue(-10.0, "S9", "C4"); 

JFreeChart chart = ChartFactory.createBarChart ("Bar 

Chart", 
"Category", "Value", dataset, PlotOrientation.VE 
RTICAL, 
true, true, false); 

response.setContentType("image/png"); 
ChartUtilities.writeChartAsPNG(out, chart, 400, 300) 


} catch (Exception e) { 
System.err.println(e.toString()); 
} finally { 
out.close(); 
} 


当 一 个 客户 端 (通常 是 一 个 web 浏 览 器 ) 发 出 一 个 请 求 时 ，Servlet 引 营 调 用 
DoGet() 方 法 ， 以 响应 这 个 请 求 ，servlet 执 行 下 面 几 步 : 


为 客户 端 返回 的 输出 获得 一 个 输出 流 引 用 

创建 一 个 图 表 ; 

Ce r 这 告诉 客户 端 接受 的 数据 类 型 是 什么 
一 个 图 表 的 PNG 图 表 beii 写 进 输 出 流 3 

输 出 流 关 闭 9 


19.3 编译 实例 Servlet 


注意 在 javax.servlet.* 包 (包括 子 包 ) 内 的 类 ， 也 就 是 实例 使 用 的 servlet， 并 不 是 
J2SE 的 一 部 分 。 为 了 使 用 J2SE 编 译 上 面 的 代码 需要 另 一 个 jar 文 件 servlet.jar。 我 们 
使 用 了 tomcat (是 用 java 编 写 的 一 个 开源 servlet 引 擎 ) 版 本 下 面 的 这 个 servlet.jar 文 
件 。Tomcat 可 以 在 下 面 链接 中 获得 : 


http://tomcat.apache.org/ 


同时 我 们 需要 JFreeChat 和 JCommon 两 个 类 包 文 件 来 编译 上 面 的 代码 。 改 变 我 们 当 
前 的 工作 目录 ， 输 入 下 面 的 命令 (如果 在 Windows 上 ， 你 需要 将 冒号 “ : “更 改 为 分 


Wik o bb 
d 


号 


javac -classpath jfreechart-1.0.6.jar:lib/jcommon-1.0.9.jar:lib/ 
servlet.jar 
source/demo/ServletDemo1. java 


这 样 就 生成 了 一 个 ServletDemo1.class 文 件 ， 下 一 章 内 容 描述 了 如 何 使 用 Tomcat 部 
署 这 个 servlet 。 


19.4 264 & #| Servlet 


Servlets 部 署 在 我 们 服务 引擎 的 webapps 的 目录 下 面 ， 在 我 们 的 例子 中 ， 使 用 的 是 
Tomcat 5.5.20， 将 代码 部 署 在 : 


D:\apache-tomcat-5.5.20\webapps\jfreechart1 


在 webapp 目录 下 ， 创 建 一 个 目录 jfreechart1 来 存放 servlet 演 示 实 例 ， 然 后 创建 下 面 
的 结构 目录 。 


.../jfreecharti/WwEB-INF/web. xml 

.../jfreecharti/WEB-INF/1lib/jfreechart-1.0.6.jar 

.../jfreechart1/WEB-INF/1lib/jcommon-1.0.9.jar 
../jfreecharti/wEB-INF/classes/demo/ServletDemo1.class 


我 们 需要 创建 Web.xml 文 件 一 一 提供 servlet 的 信息 。 


<?xml version="1.0" encoding="ISO-8859-1"?> 
<!DOCTYPE web-app 
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" 
"http://java.sun.com/j2ee/dtds/web-app_2.2.dtd"> 
<web -app> 
<servlet> 
<servlet -name>ServletDemoi</servlet -name> 
<servlet-class>demo.ServletDemoi</servlet-class> 
</servlet> 
<servlet -mapping> 
<servlet -name>ServletDemoi</servlet -name> 
<url-pattern>/servlet/ServletDemoi</url-pattern> 
</servlet -mapping> 
</web-app> 


一 旦 上 面 的 文件 部 团 在 servlet 服 务 引 擎 上 ， 然 后 启动 我 们 的 servlet 服 务 引 擎 ， 在 
Web 浏览 器 中 输入 下 面 的 地 址 : 


http://localhost:8080/jfreechart1/servlet/ServletDemo1 
如 果 不 出 现 意 外 ， 我 们 就 会 在 浏览 器 中 看 到 如 图 19.1 所 示 的 界面 。 


19.5 在 HMTL 页 面 种 齿 入 图 表 


在 HTML 页 面 中 具 入 servlet 产生 的 图 表 图 像 也 是 可 以 的 ， 下 面 实例 ServletDemo2 演 
示 了 这 一 特征 。ServletDemo2 实 例 处 理 一 个 HTML 页 面 的 请 求 ， 该 HTML 引 用 了 另 
一 个 servlet (ServletDemo2ChartGenerator) ， 引 用 的 这 个 servlet 返 回 了 一 个 图 表 
产生 的 PNG 图 像 。 最 终 的 结果 就 是 将 图 表 钥 入 到 了 一 个 HTML 中 ， 如 图 19.2 所 示 : 
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地 址 0) @) http: //localhost:8080/jfreechartl/servlet/ServletDemo2 VY 





JFreeChart Servlet Demo 


Please choose a chart type: 
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如 图 19.2 浏览 器 中 的 ServletDemo2 
全 部 代码 如 下 


package demo; 

import java.io.I0Exception; 

import java.io.PrintWriter; 

import javax.servlet.ServletException; 
import javax.servlet.http.HttpServlet; 


import javax.servlet.http.HttpServletRequest; 

import javax.servlet.http.HttpServletResponse; 

JR 

* A basic servlet that generates an HTML page that displays a ch 
art generated 

* by JFreeChart. 

* &lt;P&gt; 

* This servlet uses another servlet (ServletDemo2ChartGenerator ) 
to create a 

* PNG image for the embedded chart. 

* &lt;P&gt; 

* This class is described in the JFreeChart Developer Guide. 

=y 

public class ServletDemo2 extends HttpServlet { 


Ps 
大 


ty 

private static final long serialVersionUID = 902404046769790 
9853L; 

[sre 

* Creates a new servlet demo. 

a 

public ServletDemo2() { 

// nothing required 
} 


JERE 

* Processes a POST request. 

* &lt;P&gt; 

* The chart.html page contains a form for generating the fir 
st request, 

* after that the HTML returned by this servlet contains the 
same form for 
generating subsequent requests. 


@param request 
the request. 
@param response 
the response. 


@throws ServletException 

if there is a servlet related problem. 
@throws IOException 

if there is an I/O problem. 


+ FF FF FF FF FF F KF HF HF F 


WA 
public void doPost(HttpServletRequest request, HttpServletRe 
sponse response) 
throws ServletException, IOException { 
Printwriter out = new PrintWriter(response.getWriter()); 
try { 
String param = request.getParameter("chart"); 
response.setContentType("text/htm1"); 
out.printin("<HTML>"); 
out.printin("<HEAD>") ; 


printin("<TITLE>JFreeChart Servlet Demo 2</TITLE 


printin("</HEAD>"); 

printin("<BODY>"); 

printin("<H2>JFreeChart Servlet Demo</H2>") ; 
println("<P>"); 

printin("Please choose a chart type:"); 

printin( "<FORM ACTION=\"ServletDemo2\" METHOD=PO 


String pieChecked = (param.equals("pie") ? " CHECKED 


String barChecked = (param.equals("bar") ? " CHECKED 


String timeChecked = (param.equals("time") ? " CHECK 


out. 
219) 
out. 
out. 
out. 
out. 
out. 
out. 
Si 
" : as 
I : Aaa es 
ED" : BENS 
out. 
LUE=\"pie\"" 
out 
LUE=\"bar\"" 
out. 
LUE=\"time\"" 
out. 
out. 
Chart\">"); 


out. 
.println("<P>"); 


out 


out. 


ype=" + param 


out. 
out. 
out. 
out. 


} catch 


println("<INPUT TYPE=\"radio\" NAME=\"chart\" VA 


+ pieChecked + "> Pie Chart"); 


.println( "<INPUT TYPE=\"radio\" NAME=\"chart\" VA 


+ barChecked + "> Bar Chart"); 
printin( "<INPUT TYPE=\"radio\" NAME=\"chart\" VA 


+ timeChecked + "> Time Series Chart"); 
println("<P>"); 
printin( "<INPUT TYPE=\"submit\" VALUE=\"Generate 


printin("</FORM>"); 
printin( "<IMG SRC=\"ServletDemo2ChartGenerator?t 


+ "\" BORDER=1 WIDTH=400 HEIGHT=300/>") ; 
printin("</BODY>"); 

printin("</HTML>"); 

flush(); 

close(); 

(Exception e) { 


System.err.println(e.toString()); 
} finally { 


out. 


} 


close(); 


注意 该 代码 是 如 何 从 响应 的 参数 获得 一 个 引用 的 ， 而 不 是 上 面 实例 中 的 一 个 输出 
流 。 愿 意 是 因为 该 servlet 将 返回 HTML 文 本 ， 与 前 章 返 回 的 二 进 制 数据 (一 个 PNG 
AA) 不 同 。 响 应 的 类 型 设置 成 为 text/html 格 式 ， 因 为 servlet 返 回 的 是 HTML 文 
件 。 重 要 的 一 点 就 是 HTML 引 用 另 一 个 servlet (ServletDemo2ChartGenerator) 中 
的 <IMG> 标 签 ，ServletDemo2ChartGenerator 创 建 了 必要 的 图 表 图 片 。HTML 使 用 
<FORM> 元 素来 建立 图 表 参 数控 制 着 实际 图 表 的 返回 。 


下 面 是 ServletDemo2ChartGenerator 的 全 部 代码 : 


package demo; 
java.io.IOException; 
java.io.OutputStream; 
javax.servlet.ServletException; 
javax.servlet.http.HttpServlet; 
javax.servlet.http.HttpServletRequest; 
javax.servlet.http.HttpServletResponse; 


import 
import 
import 
import 
import 
import 
import 
import 
import 
import 
import 
import 
import 
import 
import 
import 
import 
aha 


org 


org. 


org 


org. 
org. 
org. 
org. 


org 


org. 
org. 
org. 


.jfree. 
jfree. 
.jfree. 
jfree. 
jfree. 
jfree. 
jfree. 
.jfree. 
jfree. 
jfree. 
jfree. 


* A servlet that 
This servlet 
* is referenced in the HTML generated by ServletDemo2. 


* &1t;P&gt; 


chart.ChartFactory; 
chart.ChartUtilities; 
chart.JFreeChart; 
chart.plot.PlotOrientation; 
data.category.DefaultCategoryDataset; 
data.general.DefaultPieDataset; 
data.time.Day; 
data.time.TimeSeries; 

data. time.TimeSeriesCollection; 
data.xy.xXYDataset; 
date.SerialDate; 


returns one of three charts as a PNG image file 


* Three different charts can be generated, controlled by the “ty 
pe’ parameter. 
* The possible values are ‘pie’, ‘bar’ and ‘time’ (for time seri 


es). 


* &1t;P&gt; 


* This class is described in the JFreeChart Developer Guide. 


oy 


public class ServletDemo2ChartGenerator extends HttpServlet { 


Ps 


* 


* Default constructor. 


7 


public ServletDemo2ChartGenerator() { 
// nothing required 


} 
Vax 


a 0 i E i i i i E À 


* 
SN 


* 


Process a GET request. 


@param request 
the request. 
@param response 
the response. 


@throws ServletException 

if there is a servlet related problem. 
@throws IOException 

if there is an I/O problem. 


public void doGet(HttpServletRequest request, 


ponse response) 


throws ServletException, IOException { 


HttpServletRes 


OutputStream out = response.getOutputStream(); 


try { 


String type = request.getParameter ("type"); 


JFreeChart chart = null; 

if (type.equals("pie")) { 
chart = createPieChart(); 

} else if (type.equals("bar")) { 
chart = createBarChart(); 

} else if (type.equals("time")) { 
chart = createTimeSeriesChart(); 


} 
if (chart != null) { 


response.setContentType("image/png"); 
ChartUtilities.writeChartAsPNG(out, chart, 400, 


300); 
} catch (Exception e) { 
System.err.println(e.toString()); 
} finally { 
out.close(); 
} 
} 
JSS 


* Creates a sample pie chart. 

* 

* @return a pie chart. 

gf 

private JFreeChart createPieChart() { 
// create a dataset... 


DefaultPieDataset data = new DefaultPieDataset(); 


data.setValue("One", new Double(43.2)); 
data.setValue("Two", new Double(10.0)); 
data.setValue("Three", new Double(27.5)); 
data.setValue("Four", new Double(17.5)); 
data.setValue("Five", new Double(11.0)); 
data.setValue("Six", new Double(19.4)); 


JFreeChart chart = ChartFactory.createPieChart("Pie Char 


data, true, 
true, false); 
return chart; 


} 
[fre 
* Creates a sample bar chart. 
* @return a bar chart. 


i 
private JFreeChart createBarChart() { 


DefaultCategoryDataset dataset = new DefaultCategoryData 


set(); 


dataset.addValue(10.0, "Si", "C1"); 


dataset.addValue(4.0, "Si", "C2"); 
dataset.addValue(15.0, "Si", "C3"); 
dataset.addValue(14.0, "Si", "C4"); 
dataset.addValue(-5.0, "S2", "C1"); 
dataset.addValue(-7.0, "S2", "C2"); 
dataset.addValue(14.0, "S2", "C3"); 
dataset.addValue(-3.0, "S2", "C4"); 
dataset.addValue(6.0, "S3", "C1"); 
dataset.addValue(17.0, "S3", "C2"); 
dataset.addValue(-12.0, "S3", "C3"); 
dataset.addValue(7.0, "S3", "C4"); 
dataset.addValue(7.0, "S4", "C1"); 
dataset.addValue(15.0, "S4", "C2"); 
dataset.addValue(11.0, "S4", "C3"); 
dataset.addValue(0.0, "S4", "C4"); 
dataset.addValue(-8.0, "S5", "C1"); 
dataset.addValue(-6.0, "S5", "C2"); 
dataset.addValue(10.0, "S5", "C3"); 
dataset .addValue(-9.0, "S5", "C4"); 
dataset.addValue(9.0, "S6", "C1"); 
dataset.addValue(8.0, "S6", "C2"); 
dataset.addValue(null, "S6", "C3"); 
dataset.addValue(6.0, "S6", "C4"); 
dataset.addValue(-10.0, "S7", "C1"); 
dataset.addValue(9.0, "S7", "C2"); 
dataset.addValue(7.0, "S7", "C3"); 
dataset.addValue(7.0, "S7", "C4"); 
dataset.addValue(11.0, "S8", "C1"); 
dataset.addValue(13.0, "S8", "C2"); 
dataset.addValue(9.0, "S8", "C3"); 
dataset.addValue(9.0, "S8", "C4"); 
dataset.addValue(-3.0, "S9", "C1"); 
dataset.addValue(7.0, "S9", "C2"); 
dataset.addValue(11.0, "S9", "C3"); 
dataset.addValue(-10.0, "S9", "C4"); 
JFreeChart chart = ChartFactory.createBarChart3D("Bar Ch 
ares: 
"Category", "Value", dataset, PlotOrientation.VERTIC 
AL, true, 
true, false); 
return chart; 
} 
J 


* Creates a sample time series chart. 


* 


* @return a time series chart. 


oy 


private JFreeChart createTimeSeriesChart() { 
// here we just populate a series with random data... 


TimeSeries series = 
Day current = 
for (int i = 


new TimeSeries("Random Data"); 
new Day(1, SerialDate.JANUARY, 2001); 
0; i &lt; 100; i++) { 


series.add(current, Math.random() * 100); 


current = (Day) current.next(); 
} 
XYDataset data = new TimeSeriesCollection(series); 
JFreeChart chart = ChartFactory.createTimeSeriesChart ( 


"Time Series Chart", "Date", "Rate", data, true, tru 


e, false); 
return chart; 
} 


下 一 章 讲 述 servlet 的 支持 文件 ， 与 如 何 部 署 它们 。 


19.6 支持 文件 


Servlet 为 客户 端 产 生 典 型 的 输出 。 大 部 分 web 应 用 之 少 包含 一 个 HTML 文 件 ， 用 来 
进入 应 用 的 入 口 。 本 章 演 示 的 servlet， 使 用 index.htm| 页 面 ， 代 码 如 下 : 


<HTML> 
<HEADER> 
<TITLE>JFreeChart : Basic Servlet Demo</TITLE> 
</HEADER> 
<BODY> 
<H2>JFreeChart: Basic Servlet Demo</H2> 
<P>There are two sample servlets available: 
<ul> 
<li>a very basic servlet to generate a <a 
href="servlet/ServletDemoi">bar chart;</1li> 
<li>another servlet that allow you to select one of <a 
href="chart.html">three sample charts. The selected char 
i as 
displayed in an HTML page.</1li> 
</ul> 
</BODY> 
</HTML> 


该 页 面 上 有 两 个 链接 ， 一 个 是 实例 1 (Serviet(Demo1) ， 第 二 个 链接 是 两 一 个 
HTML 页 面 ，chart.html。 代码 如 下 : 


<HTML> 
<HEADER> 
<TITLE>JFreeChart Servlet Demo 2</TITLE> 
</HEADER> 
<BODY> 
<H2>JFreeChart Servlet Demo</H2> 
<P>Please choose a chart type: 
<FORM ACTION="Servlet/ServletDemo2" METHOD=POST> 
<INPUT TYPE="radio" NAME="Cchart" VALUE="pie" CHECKED> Pi 


e Chart 
<INPUT TYPE="radio" NAME="chart" VALUE="bar"> Bar Chart 
<INPUT TYPE="radio" NAME="Cchart" VALUE="time"> Time Seri 

es Chart 
<INPUT TYPE="Submit" VALUE="Generate Chart"> 

</FORM> 
</BODY> 
</HTML> 


第 二 个 HTML 页 面包 含 <FORM> 元 素 用 来 为 第 二 个 serlvet 指 定 一 个 参数 。 当 servlet 
运行 时 ， 返 回 自己 的 HTML，THML 包 含 一 个 <IMG> 元 素 ， 该 元 素 引 用 了 
ServletDemo2ChartGenerator “servlet ° 


19.6 支持 文件 
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19.7 %8 # Servlets 


完成 上 面 实例 代码 的 编译 厚 ， 需 要 将 它们 连同 支持 文档 部 署 到 servlet 引 擎 上， 以 便 
于 客户 端 能 够 正确 访问 。 幸 运 的 是 ， 这 些 都 非常 容易 做 到 。 


首先 是 配置 web.xml 文 件 ， 该 文件 用 来 描述 web 应 用 部 署 。 


<?xml version="1.0" encoding="ISO-8859-1"?> 
<!DOCTYPE web-app 
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" 
"http://java.sun.com/j2ee/dtds/web-app_2.2.dtd"> 
<web -app> 
<servlet> 
<servlet -name>ServletDemo1</servlet -name> 
<servlet-class>demo.ServletDemoi</servlet-class> 
</servlet> 
<servlet> 
<servlet -name>ServletDemo2</servlet -name> 
<servlet-class>demo.ServletDemo2</servlet-class> 
</servlet> 
<servlet> 
<servlet -name>ServletDemo2ChartGenerator</servlet -name> 
<servlet-class>demo.ServletDemo2ChartGenerator</servlet - 
class> 
</servlet> 
<servlet -mapping> 
<servlet -name>ServletDemoi</servlet -name> 
<url-pattern>/servlet/ServletDemoi</url-pattern> 
</servlet -mapping> 
<servlet -mapping> 
<servlet -name>ServletDemo2</servlet -name> 
<url-pattern>/servlet/ServletDemo2</url-pattern> 
</servlet -mapping> 
<servlet -mapping> 
<servlet -name>ServletDemo2ChartGenerator</servlet -name> 
<url-pattern>/servlet/ServletDemo2ChartGenerator</url-pa 
ttern> 
</servlet -mapping> 
</web-app> 


该 文件 通过 名 字 列 出 了 全 部 的 sevlets， 并 且 指 定 了 具体 类 。 实 际 的 类 被 放置 在 
servlet 引 擎 的 指定 目录 下 面 。 


最 后 的 步骤 是 将 全 部 的 文档 拷贝 到 响应 的 servlet 引 敬 的 目录 下 面 。 我 们 使 用 的 是 
servlet 引 擎 是 Tomcat。 在 Tomcat 下 的 webapps 目 录 下 面 创 建 一 个 jfreechart2 的 目 
录 ， 将 index.html 和 chart.html 文 件 拷贝 到 下 面 的 目录 : 


webapps/jfreechart2/index.html 
webapps/jfreechart2/chart.html 


接 下 来 ， 在 目录 jfreechart2 下 建立 一 个 子 目录 WEB-INFO， 将 web.xml 文 件 拷贝 到 该 
目录 下 面 。 


webapps/jfreechart2/WEB-INF/web. xm1 


WEB-INFO 目 录 下 面 创 建 子 目录 classes/demo 将 编译 的 类 放 在 该 目录 下 面 。 


webapps/jfreechart2/WEB- INF/classes/demo/ServletDemo1.class 
webapps/jfreechart2/WEB- INF/classes/demo/ServletDemo2.class 
webapps/jfreechart2/WEB-INF/classes/demo/ServletDemo2ChartGenera 
tor.class 


最 后 ， 将 相关 的 jar 找 贝 到 下 面目 录 : 


webapps/jfreechart2/WEB-INF/1ib/jcommon-1.0.9.jar 
webapps/jfreechart2/WEB-INF/1lib/jfreechart-1.0.6.jar 


ILE a Hh KAN servlets] HF > 4 Bs] a BE SP ATA: 
http://localhost:8080/jfreechart2/index.html 


如 果 全 部 文件 放置 在 适当 位 置 ， 而 不 出 现 特殊 意外 的 话 ， 我 们 将 会 看 到 上 面 图 19.2 
所 示 的 界面 。 


20 JFreeChart 相 关 技 术 


20.1 简介 


本 章节 主要 介绍 了 JFreeChart 涉 及 的 各 种 信息 。 


20.2 X11/Headless Java 


eee oe a a JFreeChart > #1114242 JFreeChart# & 
~ 睛 况 下 不 能 运行 。 这 与 运行 在 AWT 上 的 java 代 码 是 同一 个 问题 。 更 多 的 信 
见 下 面 链接 : 


http://java.sun.com/products/java-media/2D/forDevelopers/java2dfaq.html#xvfb 
同时 在 JFreeChart 的 论坛 里 面 也 有 好 多 的 信息 ， 可 以 找到 一 些 额 外 的 思路 
http://www. jfree.org/phpBB2/viewtopic.php?t=1012 


20.3 JSP 


如 果 开 发 者 在 JSP 中 使 用 JFreeChart 比 较 感 兴趣 ， 那 么 可 以 从 下 面 网 址 找到 更 多 信 
a. 


we 


http://cewolf.sourceforge.net/ 


20.4 wAAA 


图 像 在 Java 中 是 用 Image 来 描述 的 。 我 们 可 以 使 用 开发 包 里 面 的 createlmage() 方 法 
来 创建 图 像 ， 但 是 我 们 需要 意识 到 该 方法 加 载 图 像 时 不 是 同步 的 一 一 换 句 话说 ， 方 
法 返回 的 与 图 像 加 载 是 在 不 同 的 线程 中 。 这 样 会 产生 这 样 一 个 问题 就 是 在 图 像 为 完 
全 加 载 完成 时 ， 我 们 就 使 用 了 该 图 像 。 

我 们 可 以 使 用 MediaTracker 类 来 检查 图 像 加 载 的 进度 。 但 万 一 在 茶 个 地 方 我 们 需要 


在 使 用 方法 之 前 ， 必 须 确 保 图 片 完 全 加 载 完 毕 。 这 时 该 怎么 办 呢 ? 使 用 Swing 的 
Imagelcon 类 可 以 解决 我 们 这 个 问题 ， 代 码 如 下 : 





ImageIcon icon = new ImageIcon("/home/dgilbert/temp/daylight.png 
"); 


Image image = icon.getImage(); 


构造 方法 直到 图 片 完 全 加 载 完 成 后 才 返 回 ， 因 此 在 我 们 调用 方法 getlmage() 时 ， 下 
图 已 经 图 像 加 载 完 毕 。 


21 包 


21.1 概述 


下 面 内 容 讲述 了 JFreeChart 类 的 参考 信息 。 


Le 
org.jfree.chart 
org.jfree.chart.annotations 
org.jfree.chart.axis 
org.jfree.chart.editor 
org.jfree.chart.encoders 
org.jfree.chart.entity 
org.jfree.chart.event 
org.jfree.chart.imagemap 
org.jfree.chart.labels 
org.jfree.chart.needle 
org.jfree.chart.plot 


org.jfree.chart.renderer 


org.jfree.chart.renderer.category 


org.jfree.chart.renderer.xy 


org.jfree.chart.serviet 
org.jfree.chart.title 
org.jfree.chart.urls 
org.jfree.chart.util 
org.jfree.data 
org.jfree.data.category 
org.jfree.data.contour 
org.jfree.data.function 
org.jfree.data.gantt 


org.jfree.data.general 


说 明 
主 图 表 类 
注释 图 表 的 简单 框架 
轴 类 和 相关 接口 
为 图 表 提 供 的 属性 编辑 器 框架 (不 完善 ) 
写 图 象 文件 类 
描述 图 表 实 体 的 类 
事件 类 
HTML 图 片 映像 工具 类 
图 表 标 签 和 信息 提示 类 
Needle classes for the compass plot 
Plot 类 和 接口 
Renderer 的 基本 类 和 包 


Plug-in renderers for use with the 
CategoryPlot class. 


Plug-in renderers for use with the XYPlot 
Class. 


Servlet utility classes. 

图 表 标 题 类 

在 图 像 映 像 区 产生 URLs 的 接口 和 类 
实用 工具 类 

Dataset 接 口 和 类 
CategoryDataset 接 口 和 相关 类 
ContourDataset 接 口 和 相关 类 
Function2D 接 口 和 相关 类 

甘 特 图 的 dataset 接 口 和 类 

通用 的 dataset 类 


org.jfree.data.io 
org.jfree.data.jdbc 
org.jfree.data.statistics 
org.jfree.data.time 
org.jfree.data.time.ohlc 
org.jfree.data.xml 


org.jfree.data.xy 


通用 的 dataset 的 MO 类 
JDBC 相 关 的 dataset 类 

产生 统计 的 相关 类 

基于 时 间 的 dataset 接 口 和 类 
展示 高 低 开发 图 表 dataset 的 类 
从 xml 文 件 读 取 dataset 的 类 
XYDataset 接 口 和 相关 类 


更 多 的 信息 可 以 查看 javadoc 产 生 的 HTML 文 档 。 


